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Preface 


Objectives of This Manual 

The *Lisp Dictionary is a complete reference source for the essential constructs of the *Lisp 
language. It is intended to provide quick access to the definitions of all *Lisp functions, macros, 
and global variables. It is not intended to explain the conceptual basics of programming in *Lisp, 
although a glossary of important and frequently used terms is included. 


Intended Audience 

This reference dictionary is intended for readers with a working knowledge of Common Lisp, as 
described in Common Lisp: The Language, and a general understanding of the Connection 
Machine system. The Connection Machine Front-End Subsystems manual provides useful 
background information on the Connection Machine system. 


Revision Information 


This dictionary is new as of CM System Software Version 5.2. It serves as a supplement to, but 
not a replacement for, the existing *Lisp documentation. 


The following *Lisp functions are documented for the first time in this dictionary: 


abs!! bit!! 

*case case!! 

deallocate-def-vp-sets 
dpb!! *ecase 

*incf Idb!! 

•logxor logxor!! 


pvar-plist 


real part!! 


byte!! 
cis!! 
*decf 
ecase!! 
Idb—test!! 
phase!! 
sbit!! 


byte-size!! 

conjugate!! 

*defsetf 

exp!! 

•light 

ppp-css 

sinh!! 


byte-position!! 

cosh!! 

deposit-field!! 

imagpart!! 

loap 

pvar-name 

tanh!! 


•undefsetf un*defun 


unproclaim vp-set-deallocated-p 


'xor 


The following *Lisp functions are obsolete, and are not listed in this dictionary. 


dsf-v+!! 

dsf-v*!! 

•pset-grid 

sf-dot-product!! 

sf-vscale!! 


dsf-v+-constant!! 
dsf-v*-constant!! 
•pset-grid-relative 
sf—v+!! 


dsf-v-!! 

dsf-v/-constant!! 

pref-grid 

sf-v-H 


*sf-vset-components 


dsf-v—constant!! 
dsf-vscale!! 
scan-grid!! 
sf-v*!! 
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Organization of This Manual 

The *Lisp Dictionary is divided into two parts. Part I, “*Lisp Overview,” provides an overview of 
the functions, macros, and important global variables of the *Lisp language, along with a glossa¬ 
ry of essential terminology and a chapter on *Lisp data types and type declaration. Part II, “*Lisp 
Dictionary,” is a complete dictionary of all functions and macros in the *Lisp language. 

Part I. *Lisp Overview 

Part I consists of the following chapters: 


Chapter 1. ♦Lisp Functions and Macros 

The names of all functions and macros in *Lisp are listed, grouped by purpose. 

Chapter 2. ♦Lisp Global Variables 

All important global variables in *Lisp are listed and described. 


Chapter 3. *Lisp Glossary 

Essential terms and concepts used in the dictionary and in other 
documentation are listed and described. 

Chapter 4. *Lisp Type Declaration 

All *Lisp data types are described, along with information about using 
declarations and about data type coercion in *Lisp. 

Part II. ♦Lisp Dictionary 

Part II is a complete dictionary of the *Lisp language, containing entries for all *Lisp 
functions and macros. 


Related Documents 

SS The *Lisp Reference Manual Version 5.0. 

This reference manual describes the essential concepts of the *Lisp language. 

SB Supplement to the *Lisp Reference Manual Version 5.0. 

This supplement expands and updates The *Lisp Reference Manual . 

SS Paris Reference Manual Version 5.0. 

Paris ("for parallel instruction set ) is the Connection Machine system’s instruction set. 
The *Lisp language calls Paris to perform its operations. This volume is a reference 
dictionary for Paris. 

SS Connection Machine Front-End Subsystems. 

This volume describes the various front-end computers used with the Connection Ma¬ 
chine system. 
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SS Common Lisp: The Language , by Guy L. Steele Jr. (Burlington, Mass.: Digital Press, 
1984). 

This book defines the de facto industry standard Common Lisp. 

SI The Connection Machine, by W. Daniel Hillis (Cambridge, Mass.: MIT Press, 1985). 
This book explains the design issues and philosophies that led to the construction of the 
Connection Machine computer. 


Notation Conventions 

Symbol names and code examples in running text appear in bold, as in * cold-boot. Code exam¬ 
ples set off from the main text appear in a typewriter style typeface, as follows: 

(pref a 23) 

Names that stand for pieces of code (metavariables) appear in italics, as in pvar-expression. In 
function or macro definitions, argument names appear in italics. Keywords and argument list 
symbols (&optional, &rest, etc.) appear in bold: 

pref pvar-expression send-address &key :vp-set 

Argument names typically indicate the data type(s) accepted for that argument; for example, 
argument names containing the term pvar must be parallel variables. The name integer-pvar re¬ 
stricts an argument to a parallel variable with integer values. Functions typically signal an error 
when given arguments of an improper type. 

The table below summarizes these notation conventions: 


Convention 

Meaning 

boldface 

Symbol names, keywords, and code examples in text. 

italics 

Metavariables and argument names. 

typewriter 

Code examples set off from text. 

=> 

Evaluates to. 

==> 

Expands into (macros, for example). 

<=> 

Are equivalent (produce the same result). 




Customer Support 


Thinking Machines Customer Support encourages customers to report errors in Connection 
Machine operation and to suggest improvements in our products. 

When reporting an error, please provide as much information as possible to help us identify and 
correct the problem. A code example that failed to execute, a session transcript, the record of a 
backtrace, or other such information can greatly reduce the time it takes Thinking Machines to 
respond to the report. 

To contact Thinking Machines Customer Support: 


U.S. Mail: Thinking Machines Corporation 

Customer Support 
245 First Street 

Cambridge, Massachusetts 02142-1214 

Internet 

Electronic Mail: customer-support@think.com 

Usenet 

Electronic Mail: ames!think!customer-support 


Telephone: 


(617) 876-1111 


For Symbolics users only: 

The Symbolics Lisp machine, when connected to the Internet network, provides a special mail 
facility for automatic reporting of Connection Machine system errors. When such an error oc¬ 
curs, simply press Ctrl-M to create a report. In the mail window that appears, the To: field 
should be addressed as follows: 

To: customer-support@think.com 

Please supplement the automatic report with any further pertinent information. 
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Chapter 1 

*Lisp Functions and Macros 



This chapter provides an overview of the functions and macros of *Lisp, organized in 
categories of functionally related operations. Only the names of functions are shown; 
consult the corresponding entry in the dictionary for argument lists and descriptions. 


1.1 Basic Pvar Operations 

*Lisp includes basic operations to allocate, access, modify, and deallocate pvars. 


1.1.1 Pvar Allocation 

These operations allocate/deallocate permanent pvars: 

'deallocate-'defvars 'defvar 

These operations allocate/deallocate global pvars: 

allocate!! 'deallocate 

These operations allocate local pvars for the duration of a body of code: 
Met 'let* 
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This operation returns a temporary pvar with the same value in each processor: 
M 

These operations return a temporary pvar of a specific data type: 

array!! front-end!! make-array!! 

typed-vector!! vector!! 


1.1.2 Pvar Data "type Declaration and Conversion 

These forms are used to declare/undeclare the data type of a pvar: 

'locally 'proclaim unproclaim 

These operations are used to convert pvars from one data type to another: 
coerce!! taken-as!! 


1.1.3 Pvar Referencing and Modification 

This operation is used to reference the values of a pvar: 

pref 

These operations are used to modify the values of a pvar: 

'set *setf 

These operations are used to define *$etf methods for user-defined functions: 

'defsetf 'undefsetf 

This operation is used in passing aggregate pvar elements to user-defined functions, to 
prevent copies of those elements from being made: 


alias!! 
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1.1.4 Pvar Information 

These predicate operations test the data type of a pvar: 

booleanp!! characterp!! complexp!! 

floatp!! front-end-p!! integerp!! 

numberp!! string-char-p!! structurep!! 

typep!! 

These operations return general information about a pvar: 

allocated-pvar-p describe-pvar pvar-exponent-length 

pvar-mantissa-length pvar-name pvarp 

pvar-plist pvar-type pvar-vp-set 

These operations return Paris-level information about a pvar: 

pvar-length Returns Paris field length of a pvar, in bits, 

pvar-location Returns Paris field-id of a pvar. 


These operations are used to print the values contained in a pvar: 


PPP 

ppp-address-object 

pppdbg 

pretty-print-pvar 


pppn 

ppp-css 

ppp-struct 

pretty-print-pvar-in-currently-selected-set 


1.2 *Lisp Function Definition 

These Common Lisp operations are used to define, call, and trace *Lisp functions: 

apply defun funcall 

trace untrace 

These *Lisp operations are used to define, call, and trace user-defined *Lisp functions 
that must reset the *Lisp stack (see the definition of *defun for more information): 


apply 

trace 


*defun 

un*defun 


funcall 

untrace 
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1.3 Processor Selection 


These forms conditionally bind the currently selected set of processors during the 
evaluation of their body forms or clauses: 


‘all 

*cond 

ecase!! 

‘unless 


‘case 

cond!! 

*if 

‘when 


case!! 

‘ecase 

if!! 

with-css-saved 


This form iterates over the currently selected set of processors: 

do-for-selected-processors 

These forms return a list of the send addresses of all active processors: 
list-of-active-processors loap 


1.4 Operations on Simple Pvars 

*Lisp includes specialized operations for simple (boolean, numeric, or character) 
pvars. 


1.4.1 Boolean Logical Operators 

These operations perform logical operations on boolean pvars: 


and!! 


not!! 


or!! 


xor!! 
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1.4.2 Numeric Pvar Operations 

*Lisp includes operations that perform mathematical tests and operations on numeric 
pvars. 


1.4.2.1 Numeric Predicates 

evenp!! minusp!! null!! 

oddp!! plusp!! zerop!! 


1.4.2.2 Relational Operators 


=!! 

<!! 

>!! 

/=!! 

<=!! 

>=!! 

eq!! 

eql!! 

equalp 


1.4.2.3 Math Operators 


+!! 

-!! 

*!! 

/!! 

1+1! 

1-!! 

abs!! 

ceiling!! 

compare!! 

*decf 

exp!! 

expt!! 

floor!! 

gcd!! 

*incf 

isqrt!! 

Icml! 

log!! 

max!! 

min!! 

mod!! 

random!! 

rem!! 

round!! 

signum!! 

sqrt!! 

truncate!! 



.2.4 Trigonometric Functions 


acos!! 

asin!! 

atan!! 

acosh!! 

asinh!! 

atanh!! 

cos!! 

sin!! 

tan!! 

cosh!! 

sinh!! 

tanh!! 
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1.4.2.5 Floating-Point Pvar Operators 

fceiling!! ffloor!! 

float-sign!! fround!! 

scale-float!! 


1.4.2.6 Floating-Point Pvar Information Functions 

float-epsilon!! least-positive-float!! 

most-positive-float!! most-negative-float!! 


1.4.2.7 Complex Pvar Operators 

abs!! cis!! 

conjugate!! imagpart!! 

realpart!! 


,4.2.8 Bitwise Integer Operators 


ash!! 

byte!! 

byte-position!! 

byte-size!! 

deposit-byte!! 

deposit-field!! 

dpb!! 

gray-code-from 

integer-from-gray-code!! 

integer-length!! 

integer-reverse!! 

load-byte!! 

Idb!! 

Idb—test!! 

mask-field!! 

rot!! 


4.2.9 Bitwise Logical Operators 

boolel! 

logand!! 

logandc2!! 

lotbitpl! 

logeqv!! 

logior!! 

lognor!! 

lognot!! 

logorc2!! 

logtest!! 


*Lisp Dictionary 


float!! 
f truncate!! 


least-negative-float!! 
negative-float-epsilon!! 


complex!! 

phase!! 


integer!! 


logandcl!! 

logcount!! 

lognand!! 

logorcl!! 

logxor!! 
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1.4.3 Character Pvar Operations 

*Lisp includes operations that construct, test, and compare character pvars. 


1.4.3.1 Character Pvar Operators 


character!! 

char-int!! 

digit-char!! 


char-downcase!! 

char-upcase!! 

int-char!! 


char-flipcase!! 

code-char!! 

make-char!! 


1.4.3.2 Character Pvar Attribute Operators 

char-bit!! char-bits!! 

char-font!! initialize-character 


char-code!! 

set-char-bit!! 


1.4.3.3 Character Pvar Predicates 


alpha-char-p!! 

characterp!! 

lower-case-p!! 

upper-case-p!! 


alphanumericp!! 

digit-char-p!! 

standard-char-p!! 


both-case-p!! 

graphic-char-p!! 

string-char-p!! 


1.4.3.4 Character Pvar Comparisons 


char=!! 

char/=!! 

char-equal!! 

char-not-equal!! 


char<!! 

char<=!! 

char-greaterp!! 

char-not-greaterp!! 


char>!! 

char>=!! 

char-lessp!! 

char-not-lessp!! 
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1.5 Operations on Aggregate Pvars 

*Lisp includes specialized operations for aggregate (array, structure, or front-end) 
pvars. 


1.5.1 Array Pvar Operations 

*Lisp includes operations to create, modify, and test multidimensional array pvars. 
Also included are specialized operations for one-dimensional array pvars (vectors). 


1.5.1.1 Basic Array Pvar Operations 

These operations return a temporary array pvar: 
array!! make-array!! 


These operations obtain information about an array pvar: 


•array-dimension 

•array-dimensions 

•array-element-type 

•array-rank 

•array-total-size 

array-row-major-index!! 


array-dimension!! 

array-dimensions!! 

array-in-bounds-p!! 

array-rank!! 

array-total-size!! 

sideways-array-p 


These operations access elements of array pvars: 

aref!! row-major-aref!! 

row-major-sideways-aref!! sideways-aref!! 


These operations map a function over a set of array pvars: 


amap!! 


map 
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These are specialized operations for bit-array pvars: 


bit!! 

bit-and!! 

bit-andcl!! 

bit-andc2!! 

bit-eqv!! 

bit-ior!! 

bit-nand!! 

bit-nor!! 

bit—not!! 

bit—orcl!! 

bit—orc2!! 

bit-xor!! 

sbit!! 





These operations convert arrays to and from a sideways (slicewise) orientation: 


*processorwise * sideways-array "slicewise 


1.5.1.2 Vector Pvar Operations 

These operations return a temporary vector pvar: 
typed-vector!! vector!! 

These are specialized operations for vector (one-dimensional array) pvars: 


cross-product!! 

dot-product!! 

v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

*vset-components 

vseale!! 

vscale-to-unit-vector!! 


These are specialized operations for single-float vector pvars: 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 


dsf-vscale-to-unit-vector!! 


These are serial (front-end) equivalents to the parallel vector operators: 

dot-product 

cross-product 

v+ 

v+-constant 

v—constant 

V- 

V* 

v*constant 

v/-constant 

vabs 

vabs-squared 

veeiling 

vector-normal 

vfloor 

vround 

vseale 

vscale-to-unit-vector 

vtruncate 
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These are specialized operations for sequence pvars: 


copy-seq!! 

count-if-not!! 

find!! 

length!! 

*nreverse 
nsubstitute-if-not!! 
position-if-not!! 
some!! 
substitute-if!! 


count!! 

every!! 

find-if!! 

notany!! 

nsubstitute!! 

position!! 

reduce!! 

subseq!! 

substitute-if-not!! 


count-if!! 

•fill 

find—if—not!! 

notevery!! 

nsubstitute-if!! 

position—if!! 

reverse!! 

substitute!! 


Note that in *Lisp, sequence pvars are defined as one-dimensional array (vector) 
pvars. 


1.5.2 Structure Pvar Operations 

This operation defines a parallel structure type and defines functions that create and 
access instances of that parallel structure type: 

*defstruct 


1.6 Processor Addressing Operations 

*Lisp includes operators that provide processor addressing information. 


1.6.1 Processor Enumeration, Ranking, and Sorting 

This operator enumerates the currently active processors: 

enumerate!! 

These operators rank and sort values in the currently active processors: 


rank!! 


sort!! 
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1.6.2 Send/NEWS Address Operators 

These operators provide access to the send and grid addresses of processors: 

cube-from-grid-address cube-from-grid-address!! 

cube-from-vp-grid-address cube-from-vp-grid-address!! 

grid-from-cube-address grid-f rom-cube-address!! 

grid-from-vp-cube-address grid-from-vp-cube-address!! 

self-address! 1 self-address-grid!! 

These operations are tests for off-grid processor addresses: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 


1.6.3 Address Object Operators 

These operators create and manipulate address objects: 

address-nth!! 
address-plus-nth!! 
address-rank!! 
grid!! 
self!! 


address-nth 

address-plus-nth 

address-rank 

grid 

grid-relative!! 
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1.7 Inter- and Intra-Processor Communication Operations 

*Lisp provides operations that transfer values between pvars, exchange values be¬ 
tween different processors, execute scans and reductions across processors, and per¬ 
form global tests. 


1.7.1 Inter-Pvar Communication Operators 

These operators transfer values between pvars using global routing: 
pref!! *pset 


1.7.2 NEWS Communication Operators 

These operators transfer values between pvars using NEWS communication: 

'news news!! news-border!! 

'news-direction news-direction!! 


1.7.3 Front-End Array to Pvar Communication Operators 

These operators transfer values between arrays on the front end and pvars on the 
Connection Machine: 


array-to-pvar 

pvar-to-array 


array-to-pvar-grid 

pvar-to-array-grid 
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1.7.4 Scan and Spread Operators 

These operators perform scans and reductions, and spread values across processors: 

reduce-and-spread!! scan!! 

spread!! 


1.7.5 Segment Set Scanning Operators 

These operators create and manipulate segment set objects, and perform segmented 
scans: 


create-segment-set!! 

segment-set-end-bits 

segment-set-end-address 

segment-set-start-bits 

segment-set-start-address 

segment-set-processor-not-in 

segment-set-processor-not-in 


segment-set-scan!! 
segment-set-end-bits!! 
segment-set-end-address!! 
segment-set-start-bits!! 
segment-set-start-address!! 
-any-segment 
-any-segment!! 


1.7.6 Global Communication Operators 

These operators perform a global test or function, returning a single front-end value: 


and 

•integer-length 

•logand 

logior 

•logxor 

•max 

min 

*or 

•sum 

xor 
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1.8 VP Set Operations 

These operations define, allocate, and deallocate fixed-size and flexible VP sets. 


1.8.1 VP Set Definition Operators 

This operation is used to define permanent VP sets, both fixed-size and flexible: 

def-vp-set 

These operations are used to define and allocate temporary, fixed-size VP sets: 

create-vp-set let-vp-set 

These operations are math utilities that are useful in defining the size of VP sets: 
next-power-of-two->= power-of-two-p 


1.8.2 VP Set Geometry Functions 

This operation creates geometry objects used in defining VP sets: 

create-geometry 


1.8.3 Flexible VP Set Allocation Operators 

These operations are used to modify the geometry of a flexible VP set: 

allocate-vp-set-processors allocate-processors-for-vp-set 

deallocate-vp-set-processors deallocate-processors-for-vp-set 

set-vp-set-geometry with-processors-allocated-for-vp-set 
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1.8.4 VP Set Deallocation Operators 

These operations are used to deallocate VP sets: 

deallocate-def-vp-sets deallocate-vp-set 


1.8.5 Current VP Set Operators 

These operations are used to select the current VP set: 
set-vp-set *with-vp-set 

These operators provide information about the dimensions of the current VP set: 

dimension-size dimension-address-length 


1.8.6 VP Set Operators 


These operations are used to obtain information about a VP set: 


describe-vp-set 

vp-set-dimensions 

vp-set-total-size 


vp-set-deallocated-p 

vp-set-rank 

vp-set-vp-ratio 


1.9 General Information Operations 

This operator provides a limited help function for *Lisp symbols: 

help 

This operator displays the current levels of Connection Machine heap and stack 
memory use: 


room 
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1.10 Entertainment Operations 

This operator provides access to the front-panel LED’s: 

•light 


1.11 Connection Machine Initialization Functions 

These operators reinitialize the Connection Machine system: 

*cold-boot * warm-boot 

These operators add and remove forms from the cold- and warm-boot initialization 
lists: 

add-initialization delete-initialization 

This operator toggles between the *lisp and user packages in the *Lisp interpreter and 
in the *Lisp simulator. 


lisp 
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2.1 Predefined Pvars 

These are permanent pvars that are predefined by *Lisp as parallel equivalents for the 
Common Lisp constants t and nil. It is an error to use either t!! or nil!! as the destina¬ 
tion for *set, *pset, or any other form that modifies its argument. 

This is a predefined pvar with the value nil in each processor: 

nil!! [Constant] 

This is a predefined pvar with the value t in each processor: 

t!! [Constant] 


2.2 Configuration Variables 

*Lisp provides a number of configuration-dependent variables with values that are set 
by operators such as *cold-boot, set-vp-set, and *with-vp-set. A program that de¬ 
pends only on these configuration variables will run on a Connection Machine system 
in any grid configuration and at any VP ratio. 

It is an error to access these variables before * cold-boot has been called for the first 
time. Also, the user must not modify the values of any of these configuration variables. 
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*current-cm-configuration* [Variable] 

The value of this variable is a list of integers. The nth element of the list is the size of 
the nth dimension in the current machine configuration. 


*current-grid-address-lengths* [Variable] 

The value of this variable is a list of integers. The nth element of the list defines the 
number of bits necessary to hold a grid (NEWS) address coordinate for the nth dimen¬ 
sion of the current VP set. 


*current-send-address-length* [Variable] 

The value of this variable is the number of bits needed to hold the send address of a 
single processor in the current VP set. The variable *log-number-of-processors- 
limit* is an obsolete equivalent. 


*current-vp-set* [ Variable ] 

This variable is always bound to the current VP set. Its value changes whenever the 
current VP set changes. It is bound by default to the *default-vp-set*. The operators 
set-vp-set and *with-vp-set can be used to change the current VP set. 


*default-vp-set* [Variable] 

The value of this variable is the default VP set, the VP set that is current when no other 
VP set is current. If no initial dimensions are specified, the first time *cold-boot is 
called, *default-vp-set* is bound to a two-dimensional VP set with a VP ratio of one. 


*log-number-of-processors-limit* [Variable] 

This obsolete variable is equivalent to the variable *current-send-address-length\ It 
provides the base 2 logarithm of the number of processors attached. 


*minimum-size-for-vp-set* [Variable] 

The value of this variable is the minimum number of virtual processors with which a 
VP set may be defined. In the current implementation, this is also the number of 
physical processors that is currently attached. The product of the dimensions of any 
VP set must be greater than or equal to the value of this variable. 
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*number-of-dimensions* [Variable] 

This variable is always bound to the number of dimensions in the current VP set. Its 
value changes whenever the current VP set changes. 

*number-of-processors-limit* [Variable] 

This variable is always bound to the number of virtual processors in the current VP set. 
Its value changes whenever the current VP set changes. 


2.3 Initialization List Variables 

These variables each contain a set of forms that are executed automatically before and 
after each execution of *cold-boot and *warm-boot. The *Lisp functions 
add-initialization and delete-initialization are used to add and remove forms from 
these lists. 


*after-*cold-boot-initializations* \Vciriable] 

The forms in this list are executed immediately following any call to *cold-boot. 

*after-*warm-boot-initializations* [Variable] 

The forms in this list are executed immediately following any call to *warm-boot. 

*before-*cold-boot-initializations* [Variable] 

The forms in this list are executed immediately prior to any call to * cold-boot. 

*before-*warm-boot-initializations* [Variable] 

The forms in this list are executed immediately prior to any call to *warm-boot. 
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2.4 Configuration Limits 

These constants and variables determine the size limits for specific ’"Lisp data types. 
Other than as documented here, they should not be modified in any way. 

2.4.1 Array Size Limits 

These constants are implementation-dependent limits on the dimension length, rank, 
and total size of array pvars. They should not be modified in any way. 


•array-dimension-limit [Constant] 

This is the upper exclusive bound on the extent of a single array pvar dimension. Each 
dimension specified for an array pvar must be less than *array-dimension-limit. The 
value of *array-dimension-limit is guaranteed to be greater than or equal to 1024. 


•array-rank-limit [ Constant] 

This is the upper exclusive bound on the number of dimensions a pvar array can have. 
The number of dimensions specified for a *Lisp array pvar must be less than 
•array-rank-limit. The value of *array-rank-limit is guaranteed to be greater than or 
equal to 8. 


•array-total-size-limit [i Constant ] 

This is the upper exclusive bound on the product of all the dimensions specified for an 
array pvar. The total number of elements a parallel array can have must be less than 
•array-total-size-limit. The value of *array-total-size-limit is guaranteed to be greater 
than or equal to 1024. 


2.4.2 Character Attribute Size Limits 

These variables represent user-specified limits on the length and value of the code, 
bits, and font attributes of character pvars. These variables may be set to values other 
than the defaults by calling the *Lisp function initialize-character. The value of these 
variables should not be modified by the user in any other way. 
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Note that if the initialize-character function is used, it must be called immediately 
prior to calling * cold-boot, because the values of the attribute variables below are used 
in initializing *Lisp and the Connection Machine system. 


*char-bits-length [ Variable ] 

This defines the length in bits of the bits subfield of a pvar character. The default is 
4 bits. 


*char-bits-limit [Variable] 

This is the upper exclusive bound restricting the value of the pvar character bits attrib¬ 
ute. The default is 16. 


*char-code-length [ Variable ] 

This defines the length in bits of the code subfield of a pvar character. The default is 
8 bits. Pvars of type (pvar string-char) have only a code field and are the same length as 

*char-code-length. 


*char-code-limit [Variable] 

This is the upper exclusive bound restricting the value of the pvar character code at¬ 
tribute. The default is 256. 


*char-font-length [Variable] 

This defines the length in bits of the font subfield of a pvar character. The default is 
4 bits. 


*char-font-limit [Variable] 

This is the upper exclusive bound restricting the value of the pvar character font attrib¬ 
ute. The default is 16. 


•character-length [Variable] 

This defines the total length in bits of a pvar of type pvar character. The default is 
16 bits. 
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"character-limit [Variable] 

This is the upper exclusive bound restricting the integer value contained by a pvar of 
type character. 


2.5 Error Checking 

These variables control the error-checking measures taken by the *Lisp interpreter 
and compiler in evaluating and compiling code. These variables may be freely modi¬ 
fied by the user to contain any of the specified legal values. 

"interpreter-safety* [ Variable] 

This variable determines the amount of run-time error checking performed by the 
*Lisp interpreter. The value of "interpreter-safety* must be an integer between 0 and 
3, inclusive. The effect of each setting is given below. 

0 Most run-time error checking disabled. 

1 Minimal run-time error checking; for any error signaled, an error message is 
not emitted until the next time a value is read from the CM. 

2 Reserved for future expansion, do not use. 

3 maximum run-time error checking; error messages emitted immediately. 


"safety* [Variable] 

This variable determines the amount of error-checking code generated by the *Lisp 
compiler. The value of "safety* must be an integer between 0 and 3, inclusive. The 
effect of each setting is given below. 

0 Low safety. Error conditions are prevented from being signalled. 

1 Error conditions are signalled, but notification of an error does not occur 
at the time the error takes place. 

2 Identical to a "safety* level of 3 or 1, depending on the value ( t or nil ) of the 
variable "immediate-error-if-location", modifiable at run time. 

3 High safety. Errors signalled immediately, with detailed error messages. 
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*immediate-error-if-location* {Variable] 

Determines the action taken at run-time by code compiled with a 'safety* value of 2. If 
the value of this variable is t, such code behaves as if compiled with a 'safety* value of 
3. If the value of this variable is nil, such code behaves as if compiled with a 'safety* 
value of 1. 


'warning-level' [Variable] 

This variable controls the type of warnings generated by the *Lisp compiler. The value 
of 'warning-level* must be one of the symbols : high, :normal, or :none. The effect of 
each setting is given below. 

•.high Detailed warnings emitted whenever a section of code is not compiled. 

: normal Warnings generated only for invalid arguments and type mismatches. 
:none Prevents generation of any warnings. 


2.6 *Lisp Compiler Code-Walker 

slc:*use-code-walker* [Variable] 

This boolean variable controls whether the code-walker portion of the *Lisp compiler 
is active. For more information about the code-walker, see the *Lisp Release Notes 
Version 5.2. For more information about compiling *Lisp code, see the *Lisp Compiler 
Guide Version 5.2 


2.7 Pretty-Printing Defaults 

These variables provide global defaults for the keyword arguments of all of the pvar 
pretty printing operations. Some functions do not include keywords that correspond to 
all these global variables; consult the dictionary definition of each printing function for 
a list of the keyword defaults used. 
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*ppp-default-mode* [Variable] 

This variable provides the default for the :mode keyword argument. Its initial value is 
:cube. Its other legal value is :grid. 


*ppp-default-format* [ Variable ] 

This variable provides the default value for the :format keyword argument. Its initial 
value is the string “~s ”. 


*ppp-default-per-line* [triable] 

This variable provides the default value for the :per-line keyword argument. Its initial 
value is nil. 


*ppp-default-start* [Variable] 

This variable provides the default value for the : start keyword argument. Its initial 
value is zero. 

*ppp-default-end* [Variable] 

This variable provides the default value for the: end keyword argument. Whenever the 
current VP set changes and whenever * cold-boot is called, "ppp-default-end* is reset 
to the current value of *number-of-processor$-limit\ 


*ppp-default-title* [Variable] 

This variable provides the default value for the : title keyword argument. Its initial val¬ 
ue is nil, indicating that no title should be printed. 


*ppp-default-ordering* [Variable] 

This variable provides the default value for the :ordering keyword argument. Its initial 
value is nil, indicating that no special grid dimension ordering is required. 
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*ppp-default-processor-list* [ Variable ] 

This variable provides the default value for the .-processor-list keyword argument. Its 
initial value is nil, indicating that all processors between: start and :end should be dis¬ 
played. 







Chapter 3 

*Lisp Glossary 


This chapter contains a glossary of special terms and concepts used in descriptions of 
the *Lisp language. 


3.1 Connection Machine Terminology 

These are terms directly relating to the Connection Machine and its relationship to the 
*Lisp language. 


3.1.1 Machines 


Connection 

Machine 


front end 


The Connection Machine (CM) consists of a large number of pro¬ 
cessors that operate on data in parallel, linked together by an inter¬ 
nal communications network and controlled by an external front- 
end computer. 

The external computer system that transmits instructions and data 
to the processors of the CM and receives data returned by the pro¬ 
cessors as a result of their operations is called the front end. 
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3.1.2 Processors 


processors 


physical 

processors 


virtual 

processors 


active 

processors 


currently 
selected set 


The conceptual entities that operate on data in parallel within the 
CM are called processors. Each processor has an associated local 
memory, within which data is stored and manipulated. Each pro¬ 
cessor is also connected to all other processors by an internal com¬ 
munications network. The term “processors” can be used to refer 
to the physical processors of the CM, but it is most commonly used 
to refer to the virtual processors simulated by the machine. This is 
the convention observed in this document. 

The single-bit processing units within the CM that operate on data 
in parallel are called the physical processors of the machine. Each 
physical processor simulates the actions of one or more virtual 
processors. 

The conceptual processing entities simulated by the physical pro¬ 
cessors of the CM are called virtual processors. This simulation is 
transparent to the user. No matter how many virtual processors are 
simulated, each has its own associated memory and operates inde¬ 
pendently of the others. 

Each processor maintains an internal flag that determines whether 
it is active, that is, whether or not it executes the instructions it re¬ 
ceives. Only the active processors of the CM execute any given op¬ 
eration. 

The set of all currently active CM processors is called the currently 
selected set. The currently selected set is changed by using *Lisp 
special forms such as *all, *when, *if, *cond, and 'case. 


3.1.3 Fields 

field Data is stored on the CM in fields. A field consists of a contiguous 

set of bits at the same location in the memory of each processor. 

allocation/ A field is created by allocating, or reserving, the same number of 

deallocation bits in the memory of each processor. When a field is no longer 

needed, it can be deallocated, freeing the memory for use in other 
fields. 
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value of a field The value of a field in any given processor is simply the value con¬ 
tained in the set of bits allocated for the field in that processor’s 
memory. 


3.1.4 Connection Machine Memory 


heap/stack 


cold boot 


warm boot 


Fields are allocated in two areas of memory on the CM known as 
the heap and the stack. Fields allocated on the heap are permanent, 
and persist until the user explicitly deallocates them. Fields allo¬ 
cated on the stack are temporary, and are automatically deallo¬ 
cated whenever the stack is cleared. 

The Connection Machine operation that resets the internal state of 
the machine and clears its memory is called a cold boot. All Con¬ 
nection Machine fields are deallocated during a cold boot. 

The Connection Machine operation that resets the internal state of 
the machine and clears the stack, but does not clear the heap, is 
called a warm boot. Fields allocated on the stack are deallocated 
during a warm boot. 


3.2 *Lisp Terminology 

These are terms relating to the data structures and operations of the *Lisp language. 


3.2.1 Parallel Variables (Pvars) 

parallel variable The *Lisp data structure that represents a collection of values 
stored one-per-processor on the CM is called a parallel variable, or 
pvar. A pvar consists of a field allocated on the CM and a front-end 
data structure that contains the location, length in bits, and data 
type of that field. 
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value of a pvar In any given processor, the value of a pvar is simply the value of its 
associated field in that processor. 

corresponding Given two pvars, A and B, for the value oL4 in any processor there 
value is a corresponding value of B located in the memory of the same 

processor. Operations on pvars typically act by combining the cor¬ 
responding values of two or more pvars. 

scalar value A front-end data type, such as an integer, a character, or a struc¬ 
ture object, is called a scalar value. 

pvar contents The contents of a pvar is the entire set of scalar values stored in the 
field of that pvar. 


3.2.1.1 Pvar Classes 

There are two main classes of pvars, heap pvars and stack pvars, corresponding to the 

two types of Connection Machine memory. 

heap pvars Heap pvars are relatively permanent, long-term storage locations 

for data, with global scope and dynamic extent. Heap pvars are di¬ 
vided into permanent pvars and global pvars. 

permanent pvars Permanent pvars are created by the *defvar macro. They are 
named global pvars and are automatically reallocated whenever 
the CM is cold-booted, unless explicitly deallocated by the user. 

global pvars Global pvars are created by the allocate !! function. They are iden¬ 
tical to permanent pvars, with the exception that global pvars are 
not reallocated when the CM is cold booted. 

stack pvars Stack pvars are temporary storage locations for data, with lexical 

scope and dynamic extent. They are automatically deallocated 
whenever the stack is cleared. Stack pvars are divided into local 
pvars and temporary pvars. 

local pvars Local pvars are created by the *let and *let* macros. They are allo¬ 

cated on the stack as local variables for the duration of a body of 
code. 

temporary pvars Temporary pvars are returned by most functions and macros in 
*Lisp. They are temporary storage locations intended to contain 
values only until those values are copied to pvars of one of the 
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above classes. It is an error to attempt to modify any temporary 
pvar value. 

Heap and stack pvars are divided into three conceptual classes based on the data types 

of their values: simple pvars, aggregate pvars, and general pvars. Simple and general 

pvars may also be declared as mutable pvars. 

simple pvars Simple pvars contain either boolean, numeric, or character values. 

aggregate pvars Aggregate pvars contain either arrays, structure objects, or point¬ 
ers to front-end data structures. 

general pvars General pvars can contain values of differing data types, with the 
exception that general pvars may not contain aggregate data ob¬ 
jects such as arrays or structures. General pvars are not as efficient 
as simple or aggregate pvars, because type-checking overhead is 
required by their use and because code containing general pvars 
cannot be compiled. 

mutable pvars Mutable pvars are simple or general pvars that have been declared 
to contain values of unspecified bit sizes. *Lisp code containing 
simple mutable pvars cannot be compiled as efficiently as code 
containing simple pvars of fixed size. 


3.2.2 Processor Addressing 

The value of a pvar in any processor may be accessed and modified. To do this, it is 
necessary to specify a processor’s address within the CM. There are two basic schemes 
in *Lisp for assigning addresses to processors: send addressing and grid addressing. 

configuration An abstract arrangement of processors that groups them in an 
n-dimensional array, such as a line, a plane, or a cube, is called a 
configuration. The number of dimensions in a configuration is the 
rank of that configuration. The geometry of the current VP set de¬ 
termines the current configuration. Note: the terms grid, machine 
configuration, and NEWS grid are sometimes used synonymously 
with configuration. 

send Each processor has a unique send address, roughly corresponding 

address to the location of the processor within the hardware. Send ad¬ 

dresses range between zero and one less than the total number of 
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processors. (In previous versions of *Lisp, this was referred to as 
the cube address of the processor.) 

grid address A list of coordinate integers that specify a processor’s position in a 

given configuration is called that processor’s grid address. The 
number of coordinates in a grid address must be equal to the rank 
of the configuration. For example, the grid address of a processor 
in a two-dimensional configuration is a list of two integers. 

address object An address object is a data structure that can be used as a send ad¬ 
dress but that specifies a given processor’s grid address. Address 
objects are more flexible than grid addresses because they auto¬ 
matically translate grid addresses between different processor 
configurations. This flexibility is obtained at the cost of efficiency, 
however; address objects are less efficient than other forms of pro¬ 
cessor addressing. 


3.2.3 Virtual Processor Sets 

geometry A geometry is a description of the size and shape of a particular 

configuration of virtual processors. It can be either a list of integers 
or a geometry object. 

geometry object A geometry object is a front-end data structure that contains a spe¬ 

cified geometry. It is used to define the size and shape of virtual 
processor sets. 

virtual A virtual processor set, or VP set, is an arrangement of virtual pro¬ 

processor set cessors in a specified n-dimensional geometry. A VP set can have 
pvars associated with it, and values may be transferred between 
pvars associated with different VP sets. Only one VP set, known as 
the current VP set, may be active at any given time. 

VP set object A front-end data structure defining the geometry and associated 
pvars of a virtual processor set is called a VP set object. 

VP ratio The number of virtual processors simulated by each physical pro¬ 

cessor on the CM for a given VP set is referred to as the virtual pro¬ 
cessor ratio, or VP ratio, of the VP set. 
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3.2.3.1 Classes of VP Sets 


There are two main classes of VP sets, permanent and temporary. Permanent VP sets 
are further divided into fixed-size and flexible VP sets. 


permanent 
VP set 


fixed-size 
VP set 


flexible 
VP set 


A permanent VP set is defined using the def-vp-set operator. Per¬ 
manent VP sets are automatically reallocated whenever the CM is 
cold booted, unless the user explicitly deallocates them. 

A fixed-size VP set has a specific geometry that does not change. 
Once a fixed-size VP set has been defined, it may be used immedi¬ 
ately. 

A flexible VP set is initially defined with no geometry information. 
Before a flexible VP set can be used, it must be instantiated, that is, 
provided with a temporary geometry definition. The operator 
allocate-processors-for-vp-set is used to instantiate flexible VP 
sets. 


temporary VP A temporary VP set is defined using either the create-vp-set or the 

sets let-vp-set operator. They are deallocated during a cold boot, as 

are their associated pvars. Temporary VP sets are always of fixed 
size. 


defined/ A permanent VP set is defined by the def-vp-set operator. A tern- 

instantiated porary VP set is defined either by the create-vp-set or the let-vp- 

set operator. Fixed-size VP sets may be used immediately, but flex¬ 
ible VP sets must be instantiated, or provided with a temporary ge¬ 
ometry definition, before they can be used. 


3.2.4 Important VP Sets 

current VP set At any one time, there is one active VP set; it is called the current VP 
set. Only pvars associated with the current VP set are directly ac¬ 
cessible. Unless otherwise specified, all newly declared pvars are 
associated with the current VP set. The variable *current-vp-set* 
is always bound to the current VP set. 

current The rank and size of the current VP set, i.e., the size and shape of 

configuration the set of processors currently in use, is often referred to as the cur¬ 

rent configuration of the machine. 
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default VP set When the CM is cold booted for the first time, a default VP set is 
created. Until some other VP set is created and selected, the de¬ 
fault VP set remains the current VP set and determines the current 
configuration of the CM. The variable *default-vp-set* is always 
bound to the default VP set. 


3.3 Background Terminology 

The naming convention for *Lisp operators, along with other useful background infor¬ 
mation, is described here. 

!! The names of functions and macros that return pvars generally end 

with !! (pronounced bang-bang). This suffix is meant to look like 
two parallel lines, emphasizing the parallel nature of the returned 
value(s). It is recommended that user-defined functions follow this 
convention as it improves readability and helps to indicate which 
functions return a temporary pvar result that must be copied into a 
permanent storage location. A few *Lisp macros with names that 
do not end in !!, such as 'when, *all and *let, may also return a 
pvar, depending on their arguments. 

* *Lisp functions that have side effects involving either the accessing 

or modification of pvars, but that do not return a pvar result, gener¬ 
ally have names beginning with * (pronounced star). The *Lisp (star 
lisp) language gets its name from this convention. 

parallel This phrase is used to describe the correspondence between a 

equivalent of *Lisp function and a Common Lisp function that performs a simi¬ 
lar operation. For example, mod!! is the parallel equivalent of 
Common Lisp’s mod. This means that mod!! performs the same 
calculation as mod, but that mod! ! takes parallel variables as argu¬ 
ments and performs the mod operation in each active processor. 
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This chapter describes the different types of parallel variables, or pvars, available in 
*Lisp, discusses type declaration and the rules of type coercion, and explains how to 
use type declarations in *Lisp. 


4.1 Pvar Types 


A pvar is defined by the kind of values that can be stored in it. The following pvar types 
are supported in *Lisp: 


general 

signed-byte 

complex 

array 


front-end 

unsigned-byte 

character 

structure 


boolean 

defined-float 

string-char 


For most pvar types, *Lisp provides several equivalent forms that may be used in 
declarations. For instance, for almost any valid pvar type specifier (pvar x), x-pvar is 
also a valid type specifier. 

Each pvar type is listed below with equivalent type forms. Each pair of forms 
separated by <=> is equivalent and may be used interchangeably within ‘proclaim, 
declare, and the forms, as well as with the operators coerce!! and taken-as!!. 

general 

(pvar t) <=> general-pvar 

front-end 

(pvar front-end) <=> front-end-pvar 
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boolean 


(pvar boolean) <=> boolean-pvar 


signed-byte 

(pvar (signed-byte width)) 


<=> (signed-byte-pvar width) 
<=> (signed-pvar width) 


unsigned-byte 

(pvar (unsigned-byte width)) <=> (unsigned-byte-pvar width) 

<=> (field-pvar width) 

defined-float 


(pvar 

(defined-float 

significcmd exponent)) 

(pvar 

(defined-float 

* * ) ) 

<=> 

float-pvar 

(pvar 

(defined-float 

15 8)) 

<=> 

(pvar short-float) 




<=> 

short-float-pvar 

(pvar 

(defined-float 

23 8)) 

<=> 

(pvar single-float) 




<=> 

single-float-pvar 

(pvar 

(defined-float 

52 11)) 

<=> 

(pvar double-float) 




<=> 

double-float-pvar 

(pvar 

(defined-float 

74 21)) 

<=> 

(pvar long-float) 




<=> 

long-float-pvar 


complex 

(pvar (complex (defined-float significcmd exponent))) 

(pvar (complex (defined-float * *))) <=> complex-pvar 

(pvar (complex (defined-float 15 8))) 

<=> (pvar (complex short-float)) 

<=> short-complex-pvar 

(pvar (complex (defined-float 23 8))) 

<=> (pvar (complex single-float)) 

<=> single-complex-pvar 

(pvar (complex (defined-float 52 11))) 

<=> (pvar (complex double-float)) 

<=> double-complex-pvar 

(pvar (complex (defined-float 74 21))) 

<=> (pvar (complex long-float)) 

<=> long-complex-pvar 
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character 

(pvar character) <=> character-pvar 

string-char 

(pvar string-char) <=> string-char-pvar 

array 

(pvar (array element-type dimensions)) 

<=> (array-pvar element-type dimensions) 

(pvar (vector element-type length)) 

<=> (vector-pvar element-type length) 


structure 

(pvar structure-name) <=> structure-name-pva.r 

where structure-name is a parallel structure type that has been defined by 

the *Lisp *defstruct operator. 

*Lisp also allows mutable pvar types, including general mutable pvars. These pvar 
types and the general pvar type are described in separate sections later in this chapter. 


4.2 Using Type Declarations 

Type declarations are useful for two reasons. First, interpreted code executes faster if 
type declarations are provided for all allocated pvars. Second, the *Lisp compiler will 
only compile *Lisp code that references pvars that are declared to be of a definite type. 
(For this reason, code that uses general or mutable pvars generally will not compile.) 

This section provides a basic guide to the methods and use of type declaration in *Lisp. 
It includes a description of the operators used for type declaration, along with a set of 
guidelines for the use of type declarations in user code. For more information about 
type declaration, and further examples, refer to the *Lisp Compiler Guide, Version 5.2. 

Remember that a type declaration represents a promise to the compiler that only 
values of the declared type will be assigned to a variable or produced by a form that is 
declared to be of that type. Type declarations do not cause type coercion; it is an error 
for a program to violate a type declaration, and the results of an incorrectly declared 
expression are not defined. Also, if a type declaration is changed, all compiled code 
that depends on that declaration must be recompiled. 
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4.2.1 *Lisp Code Walker 

As of Version 5.2, the *Lisp compiler includes a code walker that permits *Lisp code to 
compile more completely. The code walker is an extension of the *Lisp compiler that 
“walks” through all the individual forms of a piece of *Lisp code. It records all 
declarations it encounters and compiles each *Lisp form it finds. 

The code walker can be enabled and disabled by the user. It is disabled by default. To 
enable the code walker, set the variable slc::*use-code-walker* to t, or call the 
function compiler-options and select the code walker option. 

The *Lisp compiler has these additional capabilities when the code walker is enabled: 

:: *Lisp declarations are recognized in all locations where Common Lisp allows 
declaration forms. In particular, the *Lisp compiler recognizes declarations 
within defun, let, and let* forms without the need to use the ‘locally construct. 

ss All properly declared *Lisp forms compile, not only those within the scope of a 
*Lisp macro operator such as *set. 

Prior to the addition of the code walker, it was necessary to use the ‘locally operator to 
provide type declarations for some sections of code. Although use of the code walker 
makes this operator generally obsolete, ‘locally may be useful in rare circumstances, 
for example to provide declarations for code that is to be compiled with the code walk¬ 
er disabled. 

See the Dictionary entry on ‘locally for more information and for examples of its use. 
Refer to Section 4.1, “*Lisp Code Walker,” in *Lisp Release Notes, Version 5.2, for a 
discussion of the code walker and its effects on the compilation of *Lisp code. 

Important: The examples and rules given in the following sections all assume that the 
code walker is enabled. 


4.2.2 *Lisp Declaration Operators 

Three operators are used for type declaration in *Lisp: the Common Lisp declaration 
operators declare and the, and the *Lisp declaration operator ‘proclaim. A general 
description of the use of each of these operators appears below. 

Important: The following examples assume that the *Lisp code walker is enabled. 
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The ‘proclaim operator is used in the following ways: 

88 To declare the data type of a permanent pvar defined by ‘defvar, as in 

(♦proclaim '(type (pvar single-float) my-pvar)) 

(♦defvar my-pvar (random!! (!! 1.0))) 

which declares the permanent pvar my-pvar to be of type (pvar single-float). 

88 To declare the pvar data type returned by a user-defined *Lisp function, as in 

(♦proclaim 
'(ftype 

(function (pvar pvar) (field-pvar 16)) 
my-pvar-function)) 

which declares that the pvar returned by the function my-pvar-function is of 
type (field-pvar 16). 

is To declare the data type of scalar variables and user-defined functions that are 
used in a pvar expression (any expression that returns a pvar as its value), as in 
the following examples: 

(♦proclaim 

'(type (unsigned-byte 8) *my-limit*)) 

(♦defvar *my-limit* 20) 

(♦set data-pvar 

( + ! ! (random!! (!! *my-limit*)) 

(random!! (!! *my-limit*)))) 

the global variable *my-limit* used in the two calls to !! is declared to be of 
type (unsigned-byte 8). 

An example of a function declaration is given by the expressions 

(♦proclaim '(function die-roll () fixnum)) 

(defun die-roll () (+ (random 6) (random 6) 2)) 

(♦set dice-pvar (!! (die-roll))) 

in which the user-defined function die-roll is declared to return a fixnum result. 

Important: Do not use ‘proclaim to declare the returned values of Common 
Lisp functions. Instead, use the Common Lisp the operator as shown in the 
section on the below. 
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The Common Lisp declare operator is used in the following ways: 

81 To declare the pvar data type of local pvars created by *let or *let\ as in 

(♦let ((pvar-1 (random!! (!! 1.0))) 

(pvar-2 (random!! (!! 10))) 

(declare (type single-float-pvar pvar-1)) 

(declare (type (field-pvar 8) pvar-1)) 
(pvar-computation pvar-1 pvar-2)) 


88 To declare the data types of arguments to functions defined by defun or 
* defun. For example, 

(♦defun pvar-computation (pvar-1 pvar-2) 

(declare (type single-float-pvar pvar-1)) 

(declare (type (field-pvar 8) pvar-2)) 

(combine-pvars pvar-1 pvar-2)) 

88 To declare the data types of scalar local and looping variables, as in 

(let ((limit ( + 2 (random 8)))) 

(declare (type fixnum limit)) 

(♦let ((sum-pvar (!! 0))) 

(do ((i 0 ( + i 2))) 

((>= i limit) sum-pvar) 

(declare (type fixnum i)) 

(♦set sum-pvar 

(+!! sum-pvar (random!! (!! i)) 

(random!! (!! limit))))))) 

The Common Lisp the operator is used to declare the data type of an expression in 
situations not covered by either of the above two operators. 

88 To declare the data type returned by a Common Lisp expression, as in 

(♦set data-pvar 

(!! (the (unsigned-byte 32) 

( + normal-limit extra-limit)))) 
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U Tb make “on the spot” declarations where a single inline declaration is 
preferable to a more global, widespread declaration. For example, 

(*set data-pvar 

(log!! (the double-float-pvar figures-pvar))) 

(•set (the (pvar unsigned-byte 16) data-pvar) 

(the (pvar (unsigned-byte *)) 

(if store-three-pvar-p (!! 3) (!! 0)))) 

Note that it is no less efficient to use * proclaim or declare in place of the wherever this 
is possible, i.e., in declaring the data types of pvars and the data types returned by 
user-defined *Lisp functions. Readability and maintainability of code can often be 
improved by doing so. 


4.2.3 Basic Rules of Type Declaration 

The following is a set of basic guidelines for the declaration of *Lisp data objects. 
These rules describe the data objects that must be declared in order to permit code to 
compile, and describe how these objects should be declared. These rules also describe 
which data objects should not be declared. 

Declaring Pvars 

H Declare with 'proclaim the data type of permanent pvars defined by 'defvar. 

is Declare with declare or the the data type of global pvars created by allocate!! 
wherever these pvars are used. 

H Declare with declare the data type of local pvars defined by *let and 'let*. 
IS Don’t declare the pvar data type of temporary pvars returned by !!. 

Declaring Pvar Functions 

H Declare with declare the arguments of a user-defined *Lisp function (i.e., a 
function defined by either defun or *defun). 

H Declare with 'proclaim the returned value of a user-defined *Lisp function. 

ss Don’t declare the pvar data type returned by any predefined *Lisp operator. 





44 


*Lisp Dictionary 


Declaring Scalar Expressions 

u Declare with * proclaim the data type of any scalar global variable that is used 
in a pvar expression. 

Si Declare with declare the data type of any scalar local variable that is used in a 
pvar expression (i.e., a variable defined by let, let*, or the do family of looping 
operators). 

s: Declare with the the data type of any scalar expression other than a variable 
(i.e., a call to a Common Lisp function) that is used in a pvar expression. 

:s Don’t declare the data type of scalar constants used in pvar expressions. 

Important: These rules assume that the *Lisp code walker is enabled. For a 
description of the code walker, see Section 1.2.1, above. 

The next three sections provide examples for each of these rules. 


4.2.3.1 Declaring Pvars 

u Declare with 'proclaim the data type of permanent pvars defined by *defvar. 
For example, the expressions 

(♦proclaim '(type (pvar (unsigned-byte 8)) permanent-pvar)) 
(♦defvar permanent-pvar (random!! (!! 255))) 

(♦proclaim '(type boolean-pvar y-or-n-p-pvar)) 

(♦defvar y-or-n-p-pvar (zerop!! (random!! (!! 2)))) 

declare permanent-pvar to be of type (pvar (unsigned-byte 8)), and 
y-or-n-p-pvar to be of type boolean-pvar. 


ss Declare with declare or the the data type of global pvars created by allocate!! 
wherever these pvars are used. For example, in 

(setq allocated-pvar 

(allocate!! (!! 0.0) nil 'single-float-pvar)) 

(♦set (the single-float-pvar allocated-pvar) 

(random!! (!! 10.0))) 

(dotimes (i 3) 

(♦incf data-pvar 

(the single-float-pvar allocated-pvar)))) 
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the the operator is used to declare allocated-pvar to be of type 

single-float-pvar. 

Another example is 

(defvar float-pvars nil) 

(dotimes (i 10) 

(push (allocate!! (!! 0.0) nil 'single-float-pvar) 
float-pvars)) 

(defun randomize-nth-pvar (n) 

(♦set (the single-float-pvar (nth n float-pvars)) 

(random!! (!! 1.0)))) 

in which the is used to declare whichever allocated pvar is selected from the 

float-pvars list to be of type single-float-pvar. 

II Declare with declare the data type of local pvars defined by Met and Met*. 

For example, 

(♦let ((local-pvar (random!! (!! 32)))) 

(declare (type (unsigned-byte-pvar 8) local-pvar)) 

(*!! (+!! local-pvar local-pvar) (!! 2))) 

(♦let* ((float-pvar (random!! (!! 5.0))) 

(integer-pvar (floor!! float-pvar))) 

(declare (type short-float-pvar float-pvar)) 

(declare (type (field-pvar 6) integer-pvar)) 

(abs!! (-!! float-pvar integer-pvar))) 


ll Don’t declare the pvar data type of temporary pvars returned by !!. 
For example, the following declarations are unnecessary: 

;;; These declarations are unnecessary. 

(the (unsigned-byte-pvar 5) (!! 3)) 

(the character-pvar (!! #\C)) 

(the (array-pvar single-float (3)) (!! #(1.0 2.0 3.0))) 
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4.2.3.2 Declaring Pvar Functions 

:: Declare with declare the arguments of a user-defined *Lisp function (i.e., a 
function defined by either defun or *defun). 

For example, in 

(♦defun global-range (argument-pvar) 

(declare (type (field-pvat 256) argument-pvar)) 

(- (*max argument-pvar) (*min argument-pvar))) 

the argument-pvar to global-range is declared to be of type (field-pvar 256), 
and in 

(defun zero-pvar-when (test-pvar float-pvar) 

(declare (type boolean-pvar test-pvar)) 

(declare (type double-float-pvar float-pvar)) 

(if!! test-pvar float-pvar (!! 0.0))) 

the test-pvar argument is declared to be of type boolean-pvar, and the 
float-pvar argument of type double-float-pvar. 


H Declare with ’proclaim the returned value of a user-defined *Lisp function. 
For example, in 

(♦proclaim 

"(function surface-area!! (pvar pvar) 

(pvar single-float))) 

the function surface-area!! is declared to return a pvar argument of type 
(pvar single-float) while in 

(♦proclaim 

'(ftype (function (pvar) boolean) interesting-float-p)) 

the function interesting-float-p is declared to return a single argument of type 

boolean. 
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as Don't declare the pvar data type returned by any predefined *Lisp operator. 
For example, the following declarations are unnecessary: 

;;; These declarations are unnecessary. 

(♦proclaim '(function evenp!! (t t) (pvar boolean))) 
(♦proclaim '(ftype (function (t) boolean-pvar) evenp!!)) 
(♦set data-pvar (the single-float-pvar (log!! (!! 3)))) 


4.2.3.3 Declaring Scalar Expressions 

88 Declare with * proclaim the data type of any scalar global variable that is used 
in a pvar expression. 

For example, in 

(♦proclaim '(type single-float global-variable)) 

(defvar global-variable 50) 

(♦set data-pvar (log!! (!! global-variable))) 

the global-variable used to initialize data-pvar is declared to be of type 
single-float while in 

(♦proclaim '(type character special-char)) 

(defvar special-char #\Return) 

(♦if (char=M char-pvar (!! special-char)) 
(handle-special-char char-pvar) 

(handle-normal-char char-pvar)) 

the variable special-char is declared to be of type character. Note that the 
* proclaim operator must be used instead of Common Lisp's proclaim. Other¬ 
wise, the *Lisp compiler will not have access to these declarations. 


88 Declare with declare the data type of any scalar local variable that is used in a 
pvar expression (i.e., a variable defined by let, let*, or the do family of looping 
operators). For example, in 

(do ((i 1 (♦ i 2))) 

((> i 256) data-pvar) 

(declare (type fixnum i)) 

(♦incf (data-pvar (!! i)))) 

the iteration variable i is declared to be of type fixnum. 
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Another example is the expression 

(let ((maximum-limit 10) 

(minimum-limit 2.5)) 

(declare (type fixnum maximum-limit)) 

(declare (type single-float minimum-limit)) 

(♦set condition-pvar 
(cond!! 

((>!! highest-reading-pvar (!! maximum-limit)) 
(front-end-pvar!! 'T00-HIGH)) 

((<!! lowest-reading-pvar (!! minimum-limit)) 

(front-end-pvar!! 'T00-L0W)) 

(t!! (front-end-pvar 'WITHIN-LIMITS))))) 

in which the local variables maximum-limit and minimum-limit are declared 
to be of type fixnum and type single-float, respectively. 

Important: Because the iteration variable defined by a call to dotimes is always 
of type fixnum, it is unnecessary to use declare to declare the type of this vari¬ 
able. For example, 

;;; The declaration in this dotimes call is unnecessary, 
(dotimes (i 50) (*incf data-pvar (!! (the fixnum i)))) 

ll Declare with the the data type of any scalar expression other than a variable 
(i.e., a call to a Common Lisp function) that is used in a pvar expression. 

For example, in 

(♦proclaim '(type fixnum sum elements)) 

(♦set data-pvar (!! (the short-float (/ sum elements)))) 
the expression (/ sum elements) is declared to be of type short-float, and in 

(♦proclaim '(type fixnum total)) 

(♦set data-pvar (+!! (!! (the fixnum (+ total 4))) 

(!! (the fixnum (- total 4))))) 

the expressions (+ total 4) and (- total 4) are declared to be of type fixnum. 

Note that all variables used in these scalar expressions must also be declared, 
as shown in this example. 
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ss Don’t declare the data type of scalar constants used in pvar expressions. 
For example, the following declarations are unnecessary. 

;;; The declarations in these forms are unnecessary. 

(♦set pi-pvar (!! (the short-float 3.14159))) 

(♦set space-char-pvar (!! (the character #\Space))) 

(♦set array-pvar (!! (the (array fixnum (5)) 

#(1234 5)))) 


4.3 General Pvars 

This section describes in more detail the general pvar data type. 

(pvar t) 

A pvar that is declared explicitly as (pvar t) is a general pvar. Before a general pvar is 
initialized, it is referred to as void. 

General pvars are allowed to contain, in different processors at the same time, data 
belonging to any pvar type except the array or structure types. 

Whenever a general pvar is used, *Lisp checks to see which data types it contains. 
Then, each data type the general pvar contains is checked to verify that it satisfies the 
domain requirements of the operation being performed. All this run-time checking 
takes time. General pvars therefore offer almost complete generality with a corre¬ 
spondingly severe reduction in run time efficiency. 

When data of a particular type is stored in a general pvar, *Lisp ensures that the pa¬ 
rameters for that type are identical across all the values of that type. If an attempt is 
made to store pvars of the same type but with divergent parameters into a general pvar, 
*Lisp will coerce each pvar into a single type with identical parameters. 

For example, when source values of type (defined-float 52 8) are stored in a general 
pvar containing values of type (defined-float 23 11 ), the source values are copied and 
they and all the original values in the destination are coerced into type 

(defined-float 52 11). 

General pvars can receive data from any pvar that is not of type array or structure. 
When data of a particular pvar type is stored in a general pvar, *Lisp applies rules of 
type coercion specific to that pvar type. 
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Within a *set form, a general pvar destination is always expanded as necessary to hold 
whatever size data is provided by the source. If the source is a general pvar, *set 
executes as though it were called once for each type of data contained in the source 
general pvar. Thus, given a general pvar source containing boolean, signed-byte, and 
complex data, the *set operation effectively performs the following sequence. First, 
only the processors containing boolean data are activated. Next, the boolean data is 
copied to a boolean pvar. Finally, *set is called with the general destination pvar and 
the boolean source pvar. This process is repeated for the signed-byte and complex 
data types. 

If a *set with a general pvar destination does not have a general pvar source, the *set 
operation depends on the type of the source pvar, as described under each pvar type in 
Section 4.6, “Rules of *Lisp Type Declaration and Coercion,” below. 


4.4 Mutable Pvars 

Pvars may be declared to be mutable , which allows them to contain data of varying size 
and type. To declare a pvar as mutable, specify the symbol * in place of one or more 
parameters in the type specification of the pvar. For example, 

(♦let (mutable-signed-pvar) 

(declare (type (signed-pvar *) mutable-signed-pvar)) 

. . .) 

(♦proclaim '(type (pvar (defined-float ♦ ♦)) 
mutable-float-pvar)) 

(♦defvar mutable-float-pvar) 


4.5 Mutable General Pvars 

Pvars that are not declared to be of a specific type default to a type known as mutable 
general. Before a mutable general pvar is initialized, it is said to be void. 

This is the form used within declarations to explicitly declare a mutable general pvar: 


(pvar *) 
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For example, the following forms proclaim random-mutable-pvar to be a mutable gen¬ 
eral pvar and then allocate the pvar random-mutable-pvar. 

(♦proclaim "(type (pvar *) random-mutable-pvar)) 

(♦defvar random-mutable-pvar) 

If a mutable general pvar is void and a pvar of any specific data type is *set into it, then 
the mutable general pvar will assume the characteristics of that type, but will retain its 
status as a mutable general pvar. Once a mutable general pvar has contained data of 
two or more distinct types, however, it loses its mutable quality and becomes an 
ordinary general pvar. For example, if a pvar declared to be of type (pvar *) has both 
integers and characters stored in it, it becomes a pvar of type (pvar t). 

For the purpose of this definition, the following groups of pvar types are considered as 
distinct with respect to their effect on a mutable general pvar: 

boolean 

signed-byte and unsigned-byte 
character and string-char 
defined-float 
complex 

The signed-byte pvar type is considered a super type that subsumes the 
unsigned-byte pvar type. Similarly, the character pvar type is considered to subsume 
the string-char pvar type. Thus, during a session, a mutable general pvar may hold 
both string-char and character data and still retain its status as a mutable general 
pvar. Similarly, if a mutable general pvar of type unsigned-byte has signed-byte data 
stored in it, it changes into a mutable general pvar of type signed-byte. 

This is significant because if a mutable general pvar has held only one distinct type of 
data, no tests are performed on the types it contains. Thus, the run-time execution 
speed of code using mutable general pvars that have held only one distinct type of data 
is much faster than the execution speed of the same code using general pvars. 

Given these distinctions in type membership, so long as no data of a different type is 
*set into a mutable general pvar, the mutable general pvar will behave exactly as 
though it was a mutable pvar of the same type as the data last stored it. 

Aggregate (array and structure) pvars are a special case. Aggregate pvars may only be 
*set into a mutable general pvar if the mutable general pvar is void. In this case, the 
mutable general pvar ceases to be a mutable general pvar and becomes an aggregate 
pvar of the same type and size as the source pvar. 
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4.6 Rules of *Lisp Type Declaration and Coercion 

This section defines the *Lisp rules of type declaration and coercion. For each *Lisp 
pvar type listed below, the following questions are answered: 

is Can pvars of this type be declared mutable? 

u What types of data can be stored into a pvar of this type? 

H What type coercions take place if the data is not of the same type as the pvar? 

n What happens when data of this type is stored in a general pvar? 

In each case, the latter two questions are answered by explaining the type coercions 
that occur when *set is used to copy a pvar of one type into a pvar of another type. 
Coercions performed by other *Lisp operators (such as coerce!!) behave similarly. 

Note that when *set is used to copy values from a source pvar into a destination pvar, 
the source pvar is copied and then type converted if necessary. The (possibly 
converted) copy of the source pvar is then stored in the destination pvar. No coercion 
takes place on the original copy of the source pvar. 

(pvar boolean) boolean-pvar 

Boolean pvars have no parameters associated with them and are therefore never 
mutable. 

When boolean values are stored in a general pvar, no type conversion is performed. 

Within *set forms, boolean destination pvars can receive data of type boolean only. 

A general pvar can be *set into a boolean pvar if and only if all the active data in the 
general pvar is boolean. 

(pvar front-end) 

Front-end pvars have no parameters associated with them and are therefore never mu¬ 
table. 

When front-end values are stored in a general pvar, no type conversion is performed. 

Within *set forms, front-end destination pvars can receive data of type front-end only. 

A general pvar can be*set into a front-end pvar if and only if all the active data in the 
general pvar is of type front-end. 
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(pvar string-char) string-char-pvar 

Pvars of type string-char have no parameters associated with them and therefore can 
never be declared as mutable. 

When data of type string-char is put into a general pvar, it is first converted to type 

character. 

Within *set forms, string-char destination pvars can receive data of type string-char 
or type character only. If the source pvar is of the character data type, then the 
expression (*and (string-char-p!! source)) must return t. 

A general pvar can be *set into a string-char pvar if and only if all active data in the 
general pvar is of type string-char. That is, (*set destination source) is valid if 
destination is a string-char pvar and if (*and (string-char-p!! source)) returns t for the 
general pvar source. 

(pvar character) character-pvar 

Character pvars have no parameters associated with them and therefore can never be 
declared as mutable. 

When character data is put into a general pvar, no type conversion is performed. 

Within *set forms, character destination pvars can receive source data of type 
string-char or of type character only. 

A general pvar can be *set into a character pvar if and only if all the active data in the 
general pvar is of type string-char or of type character. 

(pvar (unsigned-byte length)) (field-pvar length) 

Pvars of type unsigned-byte are also known as field pvars. They have one parameter 
associated with them, a length in bits. This length may be specified as any positive 
integer, or as *. Pvars declared as (pvar (unsigned-byte *)) or (field-pvar *) are 
mutable. For instance, 

(declare (type (field-pvar 16)) ubsixteen) 
declares an unsigned-byte pvar of exactly 16 bits per processor. On the other hand, 
(declare (type (field-pvar *)) ub-mut) 


declares a mutable unsigned-byte pvar. 
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Pvars declared as (pvar (unsigned-byte *)) are initially allocated 1 bit per processor. 
They can, however, contain unsigned values of any length. 

When data of type unsigned-byte is put into a general pvar, it is first converted to an 
equivalent quantity of type signed-byte. 

Within *set forms, destination pvars of type unsigned-byte can receive source data of 
type unsigned-byte or of type signed-byte only. If the source data is of type 
signed-byte, then all the data values must be non-negative; the source data is coerced 
to type unsigned-byte before storage is effected. If the destination is of type 
(unsigned-byte *), then data of any number of bits is allowed. Otherwise, it must be 
possible to represent every active datum in the source using the number of bits 
specified for the destination’s length. 

A general pvar can be *set into a pvar of type unsigned-byte if and only if all the active 
data in the general pvar satisfies all the constraints detailed in the preceding 
paragraph. 

(pvar (signed-byte length)) (signed-pvar length) 

Pvars of type signed-byte have one parameter associated with them, a length in bits. 
This length may be specified as any positive integer greater than 1, or as \ Pvars 
declared as (pvar (signed-byte *)) are mutable. For instance, 

(♦proclaim '(type (pvar (signed-byte *)) s-mut)) 

proclaims a mutable signed-byte pvar. Mutable signed-byte pvars are initially 
allocated 2 bits per processor. They can, however, contain signed values of any length. 

If source data of type signed-byte is moved into a general pvar, and if the source data 
length is larger than the length of the signed-byte data already contained in the desti¬ 
nation, the signed-byte data already contained in the general pvar destination is sign- 
extended to accommodate the increased size. 

Within *set forms, signed-byte pvars can receive source data of type unsigned-byte or 
of type signed-byte only. If the source data is of type unsigned-byte, it is coerced into 
type signed-byte before *set storage takes place. If the destination is of type 
(signed-byte *), then source data of any bit length is allowed. Otherwise, it must be 
possible to represent every active datum in the source using the same number of bits as 
the signed-byte destination. 

A general pvar can be *set into a signed-byte pvar if and only if all the active data in 
the general pvar satisfies all the constraints detailed in the preceding paragraph. 
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(pvar (defined-float significanti exponent)) 

Pvars of type defined-float have two parameters associated with them: each defines 
the number of bits allocated per processor to store a portion of a floating-point 
number. The first parameter specifies the significand length; the second parameter 
specifies the exponent length. 

The significand length may be any positive integer greater than or equal to 1 and less 
than cm:*maximum-significand-length*. The exponent length may be any positive 
integer greater than or equal to 2 and less than cm:*maximum-exponent-length*. 

Mutable defined-float pvars are declared using * instead of a value for both sig¬ 
nificand length and exponent length. For example: 

(declare (type (pvar (defined-float * *))) mut-float) 

It is illegal to specify only one of these parameters as *. Mutable floating-point pvars 
are initially allocated 23 bits for the significand and 8 for the exponent, in each 
processor—with the sign bit, the total length is 32 bits. 

When defined-float data is put into a general pvar, floating-point numbers with one 
representation may be coerced into floating-point numbers of another representation. 
If defined-float data with significand length SL and exponent length EL is copied into a 
general pvar containing defined-float data with significand length GSL and exponent 
length GEL, both the copied source and all floating-point values originally in the 
destination are coerced into a representation with (max SL GSL) significand length 
and (max EL GEL) exponent length. If there was originally no floating-point data in the 
general destination pvar, this has no effect; GSL and GEL are both zero in this case. If, 
however, floating-point data of a different representation resides in the destination 
pvar, such coercion may have repercussions with respect to overflow, underflow, 
precision, and accuracy. 

The above rule of floating-point coercion for data stored in general pvars also applies 
to data stored in mutable defined-float pvars, i.e., pvars that are declared to be of the 
type (pvar (defined-float * *)). 

Within *set forms, defined-float pvars can receive source data of type unsigned-byte, 
type signed-byte, or type defined-float only. If the source data is of type 
unsigned-byte or type signed-byte, a copy of it is converted to type defined-float 
using the *Lisp float! ! operation. This implies that, even if the destination is a mutable 
defined-float pvar, it is an error to attempt to store unsigned-byte or signed-byte 
source data in that destination unless the source data can be represented in the same 
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floating-point format as is the destination pvar data. If this error is made, an overflow 
error may be signaled depending on the interpreter or compiler safety level in use. 

If the *set source data is of the same floating-point format as that of the destination, a 
simple data copy is done. 

If the *set source data is of a floating-point format larger than the destination in either 
significand length or exponent length, and if the destination is not a mutable defined- 
float pvar, then it is an error. 

If the *set destination is a mutable defined-float pvar, then a copy of both the source 
and the destination data are converted to a floating-point representation defined by 
the maximum of their significand and exponent lengths. After this conversion, a simple 
data copy is done. 

A general pvar can be *set into a defined-float pvar if and only if all the active data in 
the general pvar satisfies the constraints in the preceding paragraphs. 

(pvar (complex (defined-float significand exponent))) 

*Lisp supports complex pvars with real and imaginary parts of type defined-float only. 

The restrictions on complex pvar parameters are identical to the restrictions on 
defined-float pvar parameters. The real and imaginary parts are always of exactly the 
same type. Mutable complex pvars are declared with a * instead of with an integer 
value for each parameter. For example, 

(♦proclaim '(type (pvar (complex (defined-float * *))) cplx-mut)) 

declares a mutable complex pvar capable of storing variably sized complex numbers. 

Since complex pvars can contain only defined-float components, the coercion rules for 
putting complex data into a general pvar are identical to those for defined-float data. 
Note however that complex data is completely independent of defined-float data with 
respect to coercion: the existence of either type of data in a general pvar does not affect 
the representation of the other type. 

The rule of complex coercion for data stored in general pvars also applies to data 
stored in mutable complex pvars. 

Within *set forms, complex pvars can receive source data of type unsigned-byte, 
signed-byte, defined-float, or complex only. If the *set source data is of type 
unsigned-byte, signed-byte, or defined-float, it is coerced into the floating-point for¬ 
mat determined by the complex destination, following the same rules as for pvars of 
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type defined-float. The source data is then converted to complex data of the same 
floating-point format as the destination, with 0.0 as its imaginary part. Finally, a simple 
data copy is done. 

General pvars can be *set into complex pvars if and only if all the active data satisfies 
the constraints in the preceding paragraph. 

(pvar (array element-type dimensions)) 

Array pvars may not be declared mutable. 

Array pvars may not be stored in general pvars. There is one exception: an array pvar 
may be stored in a void mutable general pvar. A void mutable general pvar is a pvar of 
type (pvar *) that has never had any data stored in it. When an array pvar is stored in a 
void mutable general pvar, that mutable general pvar becomes an array pvar with the 
same type and size as the array pvar which has been stored in it. 

Within *set forms, array pvars can receive source data from other arrays pvars of the 
same shape. Effectively, ‘set is called on each element of the destination and source. 
The normal rules of type coercion with respect to the destination apply to ‘set opera¬ 
tions acting on arrays. 

(pvar struct-name) 

A pvar of type struct-name may be declared only after struct-name has been defined 
with *defstruct. 

Structure pvars may not be declared mutable. 

Structure pvars may not be stored in general pvars. There is one exception: a structure 
pvar may be stored in a void mutable general pvar. A void mutable general pvar is a 
pvar of type (pvar *) that has never had any data stored in it. When a structure pvar is 
stored in a void mutable general pvar, that mutable general pvar becomes a structure 
pvar with the same type and size as the structure pvar that has been stored in it. 

Within ‘set forms, structure pvars can receive source data from other structure pvars 
of exactly the same type. A simple bit copy is performed. 
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abs!! 


abs!! [ Function ] 

Takes the absolute value of the supplied pvar. 


Syntax- 

abs!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which absolute value is calculated. 


Returned Value- 

absolute-value-pvar 

Temporary numeric pvar. In each active processor, contains 
the absolute value of the corresponding value of numeric-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The abs! ! function takes the absolute value of numeric-pvar. It returns a temporary 
pvar that contains in each active processor the absolute value of the corresponding 
value of numeric-pvar. The abs!! function provides the same functionality for nu¬ 
meric pvars as the Common Lisp function abs provides for numeric scalars. 


Examples- 

For non-complex numeric pvars, abs!! returns the positive magnitude oi numeric- 
pvar in each active processor. For example, the following are equivalent: 

(abs!! pvar) <=> (if!! (minusp!! pvar) (-!! pvar) pvar) 

(abs!! (!! -5)) <=> (!! 5) 
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For complex pvars, abs!! returns the complex magnitude of numeric-pvar in each 
active processor, as a floating-point number. 

(abs!! complex-pvar) <=> 

(sqrt!! (+!! (expt!! (realpart!! complex-pvar) (!! 2)) 

(expt!! (imagpart!! complex-pvar) (!! 2)))) 

(abs!! (!! #c(4 3))) <=> (!! 5.0) 


Notes- 

It is an error if any of the numeric-pvar arguments contains a non-numeric value in 
any active processor. 


References 




*Lisp Dictionary 


acos!! 


acos!! [Function] 

Takes the arc cosine of the supplied pvar. 


Syntax- 

acos!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which the arc cosine is calculated. 


Returned Value- 

arc-cosine-pvar Temporary numeric pvar. In each active processor, contains 
the arc cosine in radians of the corresponding value of numer¬ 
ic-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The acos!! function calculates the arc cosine of numeric-pvar in all active proces¬ 
sors. It returns a temporary pvar containing in each active processor the arc cosine 
in radians of the corresponding value of numeric-pvar. The acos!! function pro¬ 
vides the same functionality for numeric pvars as the Common Lisp function acos 
provides for numeric scalars. 
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Examples- 

If numeric-pvcir contains non-complex values, acos!! returns the arccosine in each 
active processor. For example, 

(acos!! (!! -1.0)) <=> (!! 3.1415927) 

If numeric-pvar contains complex values, acos!! returns the complex arc cosine in 
each active processor. Thus, 

(acos!! (!! #C(-1.0 0.0))) <=> (!! #c(3.1415927 0.0)) 


Notes- 

It is an error if numeric-pvar contains integer or floating-point values of magni¬ 
tude greater than 1.0 in any active processor. Complex values with magnitude 
greater than 1.0 are allowed. 

It is an error if numeric-pvar contains a non-numeric value in any active processor. 


References 
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acosh!! [Function] 

Takes the arc hyperbolic cosine of the supplied pvar. 

Syntax- 

acosh!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which the arc hyperbolic cosine is cal 
culated. 


Returned Value- 

acosh-pvar Temporary numeric pvar. In each active processor, contains 

the arc hyperbolic cosine in radians of the corresponding value 
of numeric-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The acosh!! function calculates the arc hyperbolic cosine of numeric-pvar in all 
active processors. It returns a temporary pvar containing in each active processor 
the arc hyperbolic cosine in radians of the corresponding value of numeric-pvar. 
The acosh!! function provides the same functionality for numeric pvars as the 
Common Lisp function acosh provides for numeric scalars. 


65 





acosh!! 


*Lisp Dictionary 


Examples-— 

If numeric-pvar contains non-complex values, acosh!! returns the arc hyperbolic 
cosine in each active processor. For example, 

(acosh!! (!! 11.591953)) <=> (!! 3.1415927) 

If numeric-pvar contains complex values, acosh!! returns the complex arc hyper¬ 
bolic cosine in each active processor. 

(acosh!! (!! #c(ll.591953 0.0))) <=> (!! #C(3.1415927 0.0)) 


Notes- 

It is an error if numeric-pvar contains integer or floating-point values of magni¬ 
tude less than 1.0 in any active processor. Complex values with magnitude less than 
1.0 are allowed. 

It is an error if numeric-pvar contains a non-numeric value in any active processor. 


References 
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add-initialization [Function] 

Appends a *Lisp form to one or more initialization lists, which are evaluated before 
and after *coId-boot and *warm-boot. 


Syntax- 

add-initialization name-of-form form init-list-name 

Arguments- 

name-of-form Character string. Name of initialization being added. 

form Any *Lisp form. Code to evaluate at initialization time. 

init-list-name Symbol or list of symbols. Initialization list(s) to which the code 

is to be added. 

Returned Value- 

nil Executed for side effect. 


Side Effects- 

The list or lists specified by init-list-name are modified by appending the initializa¬ 
tion specified by form. 


Description- 

The function add-initialization adds a named initialization form to one or more of 
the following *Lisp initialization lists: 

■ *before-*cold-boot-initializations* 

*Lisp code evaluated immediately prior to any call to * cold-boot. 

■ *after-*cold-boot-initializations* 

*Lisp code evaluated immediately after any call to *cold-boot. 
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■ *before-*warm-boot-initializations* 

*Lisp code evaluated immediately prior to any call to *warm-boot. 

■ *after-*warm-boot-initializations* 

*Lisp code evaluated immediately after any call to *warm-boot. 

The forms in these lists are evaluated in the order in which they were added to the 
initialization lists. 

The argument name-of-form is a character string that names the *Lisp code being 
added to the specified list(s). The argument form may be any executable *Lisp 
form. 

The init-list-name must be either one of the initialization list symbols above or a 
list of these symbols. In the latter case, the form is added to each initialization list 
named. 

The function delete-initialization may be called with name-of-form to remove the 
initialization from the list(s). 


Examples- 

The function add-initialization is the correct way to add an initialization form to 
any of the above lists. For example, 

(add-initialization "Recompute Important Pvars" 

'(recompute-important-pvars *number-of-processors-limit*) 

'*after-*cold-boot-initializations*) 

adds an initialization named “Recompute Important Pvars” to the list 
*after-*cold-boot-initializations*, which calls a user-defined function named 
recompute-important-pvars with the current number of processors. 

The same initialization can be added to more than one list. For example, 

(add-initialization "Yell About Booting" 

'(format t "*Lisp has just been booted.") 

'(*after-*cold-boot-initializations* 

*after-*warm-boot-initializations*)) 
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adds an initialization to both *after-*cold-boot-initializations* and 
*after-*warm-boot-initializations*, which displays a warning message immediate¬ 
ly after any call to *cold-boot or *warm-boot. 
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Because add-initialization is a function, the form and init-Iist-name arguments 
must be quoted if they are not meant to be evaluated during the call to add—initiali¬ 
zation. 


Notes- 

Adding two forms with the same name to the same list is permissible only if the 
forms are the same according to the function equal; otherwise an error is signaled. 


References- 

See also the related operation delete-initialization. 

See also the following Connection Machine initialization operators: 

*cold-boot ‘warm-boot 

See also the character attribute initialization operator initialize-character. 
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address-nth [Function] 

Returns the coordinate of an address object along a specified dimension. 

Syntax- 

address-nth address-object dimension 

Arguments- 

address-object Front-end address object created by the function grid. 

dimension Integer. Number of the dimension for which the grid coordi¬ 

nate of address-object is to be returned. 

Returned Value- 

coordinate Integer. The coordinate of address-object along the dimension 

specified by dimension. 

Side Effects- 

None. 


Description- 

The function address-nth returns the grid (NEWS) coordinate of address-object 
along the dimension specified by dimension. The argument dimension must be an 
integer between 0 and one less than the number of dimensions in address-object. 


Examples- 

The function address-nth returns the nth grid (NEWS) coordinate of address- 
object, where n is the dimension specified by dimension. 

(setq addr-obj (grid 12 3 0 29)) 
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(address-nth 

addr-obj 

0) 

=> 

12 

(address-nth 

addr-obj 

1) 

=> 

3 

(address-nth 

addr-obj 

2) 

=> 

0 

(address-nth 

addr-obj 

3) 

=> 

29 


Notes 


References 


See also the related operations 
address-nth!! 
address-plus 
address-plus-nth 
address-rank 
grid 

grid-relative!! 


address-plus!! 

address-plus-nth!! 

address-rank!! 

grid!! 

self!! 
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address-nth!! [Function] 

Returns a pvar containing the coordinates of the specified address objects along the 
specified dimensions. 


Syntax- 

address-nth!! address-obj-pvar dimension-pvar 


Arguments- 

address-obj-pvar Address object pvar created by the function grid!!. 

dimension-pvar Integer pvar. Number of the dimension for which the coordi¬ 
nate of the corresponding value of address-obj-pvar is deter¬ 
mined. 


Returned Value- 

coordinate-pvar Temporary integer pvar. In each active processor, contains the 
coordinate of the corresponding value of address-obj-pvar 
along the dimension specified by dimension-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, address-nth!! returns the nth grid (NEWS) coordinate of 
address-object-pvar, where n is the dimension specified by the corresponding value 
of dimension-pvar. 
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Examples- 

(address-nth!! (grid!! x y z) (!! 1)) «> (!! y) 
(address-nth!! (grid!! x y z) (!! 2)) => (!! z) 


Notes 


References- 

See also the related operations 

address-nth 

address-plus address-plus!! 

address-plus-nth address-plus-nth!! 
address-rank address-rank!! 

grid grid!! 

grid-relative!! self!! 
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address-plus [ Function ] 

Increments the coordinates of an address object. 

Syntax- 

address-plus address-obj &rest increment-values 

Arguments- 

address-obj Front-end address object created by the function grid. 

increment-values Integers. Amount by which each coordinate of the address-obj 
is to be incremented. There must be as many increment-values 
as there are dimensions in the supplied address-obj. 

Returned Value- 

inc-addresss-obj Address object. Copy of address-obj with each coordinate 
incremented by the corresponding increment-value. 

Side Effects- 

None. 

Description- 

The function address-plus increments the coordinates of address-obj. 
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Examples- 

(address-plus (grid x y) 5 7) <=> (grid (+ x 5) (+ y 7)) 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus!! 

address-plus-nth address-plus-nth!! 

address-rank address-rank!! 

grid grid!! 

grid-relative!! self!! 
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address-plus!! [ Function] 

Returns a copy of the supplied address object pvar with the coordinates of each of its 
values incremented by the specified values. 


Syntax- 

address-plus!! address-obj-pvar &rest increment-pvars 


Arguments- 

address-obj-pvar Address object pvar created by the function grid!!. 

increment-pvars Integer pvars. Amount by which each coordinate of the corre¬ 
sponding value of address-obj-pvar is to be incremented. 


Returned Value- 

inc-address-pvar Temporary address object pvar. In each active processor, con¬ 
tains a copy of the value of address-obj-pvar with each coordi¬ 
nate incremented by the value of the corresponding increment- 
pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns an address object pvar that is a copy of address-obj-pvarsNith 
each coordinate incremented by the value of the corresponding increment-pvar. 
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Examples- 

(address-plus!! (grid!! x y z) (!! 1) (!! 2) (!! 3)) 
<=> 

(grid!! (+!! x (!! 1)) (+!! y (!! 2)) (+!! z (!! 3))) 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus 

address-plus-nth address-plus-nth!! 

address-rank address-rank!! 

grid grid!! 

grid-relative!! self!! 
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address-plus-nth [Function] 

Increments the coordinate of an address object along a specified dimension. 


Syntax- 

address-plus-nth address-obj increment dimension 


Arguments- 

address-obj Front-end address object created by the function grid. 

increment Integer. Amount by which the specified dimension is to be in¬ 

cremented. 


dimension 


Integer. Zero-based number of the dimension to be increm¬ 
ented. 


Returned Value- 

inc-addresss-obj Address object. Copy of address-obj with the coordinate speci¬ 
fied by dimension incremented by increment. 


Side Effects 

None. 


Description- 

The function address-plus-nth increments the nth coordinate of address-obj, 
where n is the grid (NEWS) dimension specified by dimension. 
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Examples- 

(address-plus-nth (grid x y) 50) <=> (grid (+ x 5) y) 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth!! 
address-rank address-rank!! 

grid grid!! 

grid-relative!! self!! 
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address-plus-nth!! [Function] 

Returns a copy of the supplied address object pvar with each of its values incremented 
along the specified dimensions. 


Syntax- 

address-plus-nth!! address-obj-pvar increment-pvar dimension-pvar 


Arguments- 

address-obj-pvar Address object pvar created by the function grid!!. 

increment-pvar Integer pvar. Amount by which the dimension specified by 
dimension-pvar is to be incremented. 

dimension-pvar Integer pvar. Zero-based number of the dimension to be in¬ 
cremented. 


Returned Value-- 

inc-address-pvar Temporary address object pvar. In each active processor, con¬ 
tains a copy of the value of address-obj-pvar with the coordi¬ 
nate specified by dimension-pvar incremented by increment- 
pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns an address object pvar that is a copy of address-obj-pvarmth 
the dimension specified by dimension-pvar incremented by increment-pvar. For 
example, 
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Examples- 

(address-plus-nth!! (grid!! (! ! x) (!! y) (!! z)) 

(!! 5) (!! 1)) 

<=> 

(grid!! (!! x) (+!! y (!! 5)) (!! z)) 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth 

address-rank address-rank!! 

grid grid!! 

grid-relative!! self!! 
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address-rank [Function] 

Returns the number of coordinates specified by an address object. 

Syntax- 

address-rank address-obj 

Arguments- 

address-obj Front-end address object created by the function grid. 

Returned Value- 

rank Integer. Number of coordinates in address-obj. 

Side Effects- 

None. 

Description- 

This function returns the number of coordinates in address-obj. 
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Examples- 

(address-rank (grid x y)) => 2 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth address-plus-nth!! 

address-rank!! 
grid grid!! 

grid-relative!! self!! 
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address-rank!! [Function] 

Returns a pvar containing the number of coordinates in the specified address objects. 


Syntax- 

address-rank!! address-obj-pvar 


Arguments- 

address-obj-pvar Address object pvar created by the function grid!!. 


Returned Value- 

rank-pvar Temporary integer pvar. In each processor, contains the 

number of coordinates in the corresponding value of 
address-obj-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns in each processor the number of coordinates in the 
corresponding value of address-obj-pvar. 


85 



address-rank!! 


*Lisp Dictionary 


Examples- 

(address-rank!! (grid!! (!! x) (!! y))) <=> (!! 2) 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth address-plus-nth!! 

address-rank 

grid grid!! 

grid-relative!! self!! 


86 




*Lisp Dictionary 


alias!! 


alias!! [Macro] 

Returns the actual contents of the specified subfield of a pvar, redefined as a 
temporary pvar of appropriate size and type. 


Syntax- 

alias!! subfield-selector 


Arguments- 

subfield-selector Pvar subfield selector. Must be a call to either aref!! or 
row-major-aref!!, a call to a structure pvar slot accessor de¬ 
fined by *defstruct, or a call to one of the functions imagpart!!, 
realpart!!, or load-byte!!. 


Returned Value- 

aliased-pvar A temporary pvar of the same data type as the referenced pvar 
subfield, such that the data contained in the aliased pvar is 
identical to the data contained in the pvar subfield, rather than 
being a copy of the data (i.e., the aliased pvar references the 
same area of CM memory as the subfield selector.) 

Side Effects- 

None. 


Description- 

In *Lisp, a parallel array accessor, such as aref!! or row-major-aref!!, returns a 
temporary pvar that is a copy of the element being referenced. Likewise, a parallel 
structure slot accessor, as defined by a call to *defstruct, returns a temporary pvar 
that is a copy of the parallel structure slot being accessed. Other pvar operations 
that return subfields of a pvar, such as imagpart!!, realpart!!, and load-byte!!, by 
definition return a copy of the referenced subfield. For most purposes, this copying 
is transparent and makes no difference. 
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TWo important exceptions are: 

■ passing a pvar subfield to a user-defined function that must modify the 
subfield directly 

■ passing a pvar subfield to any function or macro where the size of the pvar 
subfield makes copying inefficient (i.e., a structure slot that contains 
another structure of considerable size). 

In these two cases, the alias! ! macro can be used to specify that the actual contents 
of the pvar subfield should be returned, rather than a copy. 

The alias! ! macro creates and returns a temporary pvar defined in such a way that 
the contents of the pvar are the actual contents of the referenced pvar subfield. The 
alias!! macro in effect “renames” or “aliases” the portion of a pvar referenced by 
the supplied subfield-selector. The aliased-pvar returned by alias!! may be freely 
referenced and modified as a pvar of the same data type as the pvar subfield. 

Important: The alias!! macro is necessary only in the two cases mentioned above. 
In all other cases, use of the alias!! macro has no effect and detracts from 
readability of code. In some cases, explicit use of the alias!! macro is redundant. 
The following functions effectively perform an alias!! operation on their 
arguments: 

*setf *pset 


Examples- 

The subfield-selector argument to alias!! can be an array reference, i.e., a call to 
either aref!! or row-major-aref!!. For example, given the array defined by 

(*defvar array-pvar (!! #2A((1 23) (456)))) 

both of the following expressions modify the same element of the array. 

(modify-array-element 

(alias!! (aref!! array-pvar (!! 1) (!! 1)))) 
(modify-array-element 

(alias!! (row-major-aref!! array-pvar (!! 4)))) 
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The subfield-selector argument to alias!! can also be a structure slot reference, i.e., 
a call to a slot accessor function created by *defstruct. 

The following code illustrates how to use alias!! with structure pvars: 

(*defstruct history-struct 

(description nil :type (vector string-char 1000)) 
(sickness-id 0 :type (unsigned-byte 32))) 

(*defstruct patient 

(id-no 0 :type (unsigned-byte 8)) 

(doctor 0 :type (unsigned-byte 8)) 

(sick-p t : type boolean) 

(case-history nil :type (pvar (array history-struct (100)))) 

) 

(defun modify-patient-slot (slot-pvar value) 

(declare (type (field-pvar•*) slot-pvar value)) 
nil 

(*set slot-pvar value)) 

(defun in-error () 

(*let ((ellen (make-patient!!))) 

(declare (type (pvar patient) ellen)) 

(modify-patient-slot (patient-sick-p!! ellen) nil!!) 

(PPP (patient-sick-p!! ellen) :end 5))) 

(defun correct () 

(*let ((ellen (make-patient!!))) 

(declare (type (pvar patient) ellen)) 

(modify-patient-slot 

(alias!! (patient-sick-p!! ellen)) nil!!) 

(PPP (patient-sick-p!! ellen) :end 5))) 

The in-error function is in error because (patient-sick-p!! ellen) returns a tempo¬ 
rary pvar containing a copy of the data in ellen’s $ick-p slot. This pvar is allocated 
on the stack. The function modify-foo-slot then attempts to *set this temporary 
pvar, rather than the actual data stored in the structure ellen. The original data is 
not modified. 

The correct function is correct because alias!! returns the actual slot sick-p from 
ellen as a pvar that can be modified by a call to the user-defined function 

modify-patient-slot. 
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The subfield-selector argument to alias! ! can also be one of the pvar subfield opera¬ 
tions imagpart!!, realpart!!, and !oad-byte!!. (Due to its implementation, alias!! 
cannot be applied to these three operators in the *Lisp simulator.) 

For example, 

(alias!! (imagpart!! complex-pvar)) 

(alias!! (realpart!! complex-pvar)) 

(alias!! (load-byte!! integer-pvar position-pvar size-pvar)) 

Besides passing pvar subfields to functions that modify those fields, alias!! may 
also be used to prevent copying of large pvar subfields. 

For example, in the expression 

(hypocondriac-p!! (alias!! (patient-case-history!! ellen))) 

the user-defined function hypochondriac-p!! does not modify the case-history 
slot of ellen. Even so, using alias!! in this expression is more efficient because it 
prevents the possibly quite large case-history slot from being copied in the process 
of passing it to the function hypochondriac-p!!. 

An example of when not to use the alias!! macro is provided by the expression 
(*set dest-pvar 

(+!! (alias!! (aref!! array-pvar (!! 0))) 

(alias!! (structure-slot!! structure-pvar)))) 

Neither of the calls to alias! ! are necessary in this expression, because no modifica¬ 
tion of the referenced location takes place. It is also unnecessary and redundant to 
apply alias! ! to the arguments of the *Lisp functions *setf and *pset. For example, 
in the expression 

(*setf (alias!! (aref!! array-pvar (!! 3))) (!! 2)) 

the *setf macro effectively performs an alias!! operation on its first argument, so 
the extra call to alias!! is unnecessary. 

Also, in many cases it is not necessary to use the operator alias!! in combination 
with aref!! to prevent the copying of large array pvars, because the *Lisp compiler 
is able to recognize and optimize cases where this copying is unnecessary. See the 
dictionary entry for aref!! for more information. 
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Notes- 

The alias!! macro may not be applied to an array reference that uses indirect ad¬ 
dressing, i.e., a call to aref !! with an index pvar containing different values in each 
processor. The alias!! macro also may not be applied to array accessors that oper¬ 
ate on arrays in sideways (slicewise) orientation. These operators are: 

sideways-aref!! row-major-sideways-aref!! 


References- 

See also the related operator 
taken-as!! 
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*all [Macro] 

Executes *Lisp forms with all processors selected. 

Syntax- 

*all &body body 

Arguments- 

body *Lisp forms. Any number of statements, which are executed in 

order. 

Returned Value- 

body-value Scalar or pvar value. Value of final form in body. 

Side Effects- 

Temporarily binds currently selected set to include all processors during execution 
of the forms in body. 

Description- 

The macro *all is one of the processor selection operations. It executes a set of 
*Lisp forms with the currently selected set bound to include all processors in the 
current VP set. The value of the final expression in the body of the *all form is re¬ 
turned. 
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Examples- 

The most common use of the *all macro is to ensure that all processors are selected 
before the execution of a section of code. For example, 

(*all 

(*set every-proc (!! 5))) 

selects all processors and then uses ‘set to store 5 as the value of every-proc in 
every processor. Using ‘all guarantees that every-proc has the same value in every 
processor after this operation. 

Processor selection macros can be nested. The expression 
(*all 

(*set numeric-pvar (random!! (!! 10.0))) 

(*when (<!! numeric-pvar (!! 1)) 

(*set numeric-pvar (/!! numeric-pvar)))) 

uses *all to select all processors, ‘set to store a random floating-point value be¬ 
tween 0 and 10 into numeric-pvar for every processor, and ‘when to select only 
those processors in which the value stored in numeric-pvar is less than 1. In these 
processors, /!! is used to calculate the reciprocal of the value in numeric-pvar, and 
‘set is used to store the calculated value back into numeric-pvar. 

Because ‘all temporarily binds the currently selected set, and restores its original 
value upon exiting, it can be used within other processor selection macros to tem¬ 
porarily reselect all processors. For example, the expression 

(*when (<!! data-pvar (!! 100)) 

(/ (*sum data-pvar) 

(*all (*sum data-pvar)))) 

uses ‘when to select those processors in which the value of data-pvar is less than 
100. The global function ‘sum is used to take the sum of the values in these proces¬ 
sors. Then ‘all is used to temporarily rebind the currently selected set so that ‘sum 
can be used to take the sum of the values of data-pvar in all processors. The result 
returned by the entire expression is the ratio between the sum of the values of data- 
pvar that are less than 100 and the sum of all values of data-pvar. 
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Notes- 

The *cold-boot and *warm-boot operations force reselection of all processors, 
but these operations also reset *Lisp and clear the *Lisp stack. See the definitions 
of * cold-boot and *warm-boot for more information. 

It is not necessary to use *all around every body of code. The *all macro is only 
necessary only in three cases: 

■ Around the body of functions that need all processors active, but are called 
from within code that restricts the currently selected set. 

■ Around any code that requires all processors to be selected temporarily. 
For example, see the selective sum and division example above, which mo¬ 
mentarily changes the currently selected set. 

■ Within code that changes the current VP set. Each VP set keeps track of its 
own currently selected set of active processors. To avoid using a previously 
restricted set of active processors when switching between VP sets, use 

*all. 

An example of the last case is: 

(def-vp-set fred '(16384)) 

(def-vp-set wilma '(8192)) 

(*with-vp-set fred 

(*when (<!! (self-address!!) (!! 100)) 

(format t ""%In FRED, # active procs should be 100, ~ 
and is: ~d" (*sum (!! 1))) 

(*with-vp-set wilma 

(format t ""%In WILMA, # active procs should be 8192, ~ 
and is ~d" (*sum (!! 1))) 

(*with-vp-set fred 

(format t "~%In FRED, the # active procs should still ~ 
be 100, and is ~d" (*sum (!! 1))) 

(*all 

(format t "In FRED, the # active procs should now ~ 
be 16384, is ~D" (*sum (!! 1))))) 

(format t "~%In WILMA, tf active procs should still ~ 
be 8192, is: ~d" (*sum (!! 1)))) 

(format t "~%In FRED, # active procs should again ~ 
be 100, is: "d" (*sum (!! 1))))) 


95 



•all 


*Lisp Dictionary 


This example produces the following output: 

In FRED, # of active procs should be 100, and is: 100 
In WILMA, # of active procs should be 8192, and is: 8192 
In FRED, # of active procs should still be 100, and is: 100 
In FRED, # of active procs should now be 16384, is: 16384 
In WILMA, # of active procs should be 8192, is: 8192 
In FRED, # of active procs should again be 100, is: 100 

Note the use of *all within the *with-vp-set forms in this example to ensure that all 
the processors of the newly selected VP set are active. Note also the use of the *Lisp 
idiom (*sum (!! 1)) to determine the number of active processors. 

Forms such as throw, return, return-from, and go may be used to exit an external 
block or looping construct from within a processor selection operator. However, 
doing so will leave the currently selected set in the state it was in at the time the 
non-local exit form is executed. To avoid this, use the *Lisp macro with-css-saved. 
For example, 

(defun safe-division (y x) 

(*when (evenp!! (self-address!!)) 

(block division 
(with-css-saved 
(*all 

(*if (>!! y ( !! 0)) 

(if (*or (=!! (!! 0) x)) 

(return-from division nil) 

(/!! y x)))))))) 

Here return-from is used to exit from the division block if the value of x in any 
processor is zero. When the with-css-saved macro is entered, it saves the state of 
the currently selected set. When the code enclosed within the with-css-saved exits 
for any reason, either normally or via a call to an non-local exit operator like 
return-from, the currently selected set is restored to its original state. 

See the dictionary entry for with-css-saved for more information. 


References 


See also the related operators 

•case case!! *cond cond!! 

*if if!! ‘unless *when 


*ecase ecase!! 
with-css-saved 
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allocate!! [Macro] 

Allocates a global pvar. 


Syntax- 

allocate!! &optional pvar-initial-value name type 


Arguments 


pvar-initial-value Pvar expression. If supplied, is value with which global pvar is 
initialized. If not supplied, a pvar with undefined values is 
created. 


name Symbol. If supplied, stored as the symbolic name of the allo¬ 

cated pvar. 

type Data type specification. If supplied, determines the data type 

of the allocated pvar. Must be compatible with data type of 
pvar-initial-value argument. If not supplied, a general mutable 
pvar is created. 


Returned Value- 

global-pvar The created global pvar is returned. 


Side Effects- 

The returned pvar is allocated on the heap. 


Description- 

This operation creates a global pvar with the specified pvar-initial-value , name, 
and type. Global pvars are deallocated during a call to * cold-boot, and are not 
automatically reallocated, as are permanent pvars created by *defvar. 
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Examples- 

Global pvars of any data type may be allocated on the heap using allocate!!: 

(setq a (allocate!! (!! 5))) 

(setq b (allocate!! (evenp!! (random!! (!! 2))) 

'new-pvar 'boolean-pvar)) 


(setq heap-pvar 

(allocate!! (!! #(1 2 3)) nil 

'(pvar (array (unsigned-byte 8) (3))))) 

(ppp heap-pvar :end 2) 

=> #(1 2 3) #(1 2 3) 

The following example shows how allocate!! may be used to allocate pvars within 
any VP set, and also how allocate!! is useful for creating an unspecifed number of 
global pvars on demand. 

(def-vp-set fred (list *minimum-size-for-vp-set*)) 

(defvar list-of-pvars nil) 

(defun main 

(*with-vp-set fred 
(loop 

(process-data) 

(when (extra-pvar-needed) 

(push (allocate!! (!! 0) nil 

'(pvar (unsigned-byte 32))) 

list-of-pvars))))) 

By defining the list-of-pvars with allocate!!, the global pvars pushed onto the list 
may be explicitly deallocated with the * deallocate operator whenever they are no 
longer needed. 
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allocate!! 


Notes- 

Usage Note: 

The allocate!! macro is intended to be called within user code, not at top level. 
It acts much like the malloc operator in the C language, in allowing the pro¬ 
grammer to dynamically allocate CM memory within a program. Pvars allo¬ 
cated using allocate!! are automatically deallocated during a *cold-boot. It is 
an error to attempt to reference a global pvar deallocated by *cold-boot. 

Language Note: 

Global pvars and permanent pvars are allocated on the CM heap. In contrast 
to global pvars, which are allocated by allocate!! and deallocated with ‘deallo¬ 
cate, permanent pvars are allocated by *defvar and must be deallocated by the 

function *deallocate-*defvars. 

A global pvar created with allocate!! is simply returned. A permanent pvar 
created with ‘defvar is bound to a global variable. Permanent pvars are reallo¬ 
cated during a call to *cold-boot; global pvars are simply deallocated. 


References- 

See also the pvar allocation and deallocation operations 

array!! 

‘deallocate *deallocate-*defvars ‘defvar 

front-end!! ‘let ‘let* 

make-array!! typed-vector!! vector!! 

!! 

See the *Lisp glossary for definitions of the different kinds of pvars that are allo¬ 
cated on the CM stack and heap. 
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allocate-processors-for-vp-set 


allocate-processors-for-vp-set [Function] 

allocate-vp-set-processors [Function] 

Instantiates the specified flexible VP set, allocating virtual processors according to the 
supplied dimensions or geometry. 


Syntax- 

allocate-processors-for-vp-set vp-set dimensions &key :geometry 

Arguments- 

vp-set Flexible VI 5 set. Virtual processor set defined with def-vp-set. 

dimensions Integer list or nil. Size of dimensions with which to instantiate 

vp-set. Must be nil if geometry argument is supplied. 

:geometry Geometry object obtained by calling the function 

create-geometry. Defines geometry of vp-set. 

Returned Value- 

nil Evaluated for side effect. 


Side Effects- 

Defines geometry of and instantiates vp-set , and allocates any associated pvars. 


Description- 

This function is used during program execution to instantiate a flexible VP set. A 
flexible VP set is a VP set that has been defined by calling def-vp-set without sup¬ 
plying specific dimensions or geometry. By omitting the geometry from a 
def-vp-set call and later calling allocate-processors-for-vp-set, it is possible to 
create VP sets with dimensions and geometries determined at run time. For exam¬ 
ple, VP set geometries might depend on characteristics of data that are read from a 
file during program execution. 
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It is an error to invoke allocate-processors-for-vp-set before *cold-boot has 
been invoked, or to pass a fixed-size VP set as an argument. 

The argument vp-set must be a flexible VP set defined by a call to the def-vp-set 
macro in which the dimensions argument was nil and the : geometry-definition- 
form keyword argument was either nil or unsupplied. 

The dimensions argument must be a list of integers or nil. If a list of integers is 
supplied, each integer must be a power of 2. The product of the dimensions must 
be at least as large as *minimum-size-for-vp-set* and, if larger than the physical 
machine size, a power-of-two multiple of the physical machine size. Such a list 
specifies the dimensions of a virtual array of processors named vp-set. The dimen¬ 
sions argument must be nil if an argument is supplied to the keyword : geometry. 

If a :geometry keyword argument is supplied, it must be a geometry object. If 
geometry is provided, it incorporates information about the dimensions of the VP 
set being defined. (A geometry object may be obtained by calling the function cre- 
ate-geometry. See the definition of create-geometry for more details.) 


Examples-- 

This example shows how allocate-processors-for-vp-set, along with its compan¬ 
ion function deallocate-processors-for-vp-set, may be used to instantiate a 
flexible VP set several times with a different geometry at each invocation. 

(def-vp-set disk-data nil 

:*defvars ((disk-data-pvar nil nil (pvar single-float)))) 


(defun process-files (&rest diskfiles) 

(*cold-boot) 

;;; at this point, disk-data-pvar has no memory allocated 

;;; on the CM 

(dolist (file diskfiles) 

(let ((elements (read-number-of-elements-in file))) 
(allocate-processors-for-vp-set disk-data 
(list (next-power-of-two->= elements))) 

;;; now disk-data-pvar has CM memory allocated 
(let ((array-of-data (read-data-from-disk file))) 
(array-to-pvar array-of-data disk-data-pvar 
:cube-address-end elements) 
(process-data-in-cm disk-data disk-data-pvar)) 
(deallocate-processors-for-vp-set disk-data)))) 
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allocate-processors-for-vp-set 


Notes- 

The function allocate-vp-set-processors is an obsolete alias for allocate- 
processors-for-vp-set, and behaves identically. 


References- 

See also the following VP set definition and deallocation operators: 

def-vp-set create-vp-set let-vp-set 

deallocate-def-vp-sets deallocate-vp-set 

See also the following geometry definition operator: 

create-geometry 

The following math utilities are useful in defining the size of VP sets: 
next-power-of-two->= power-of-two-p 

See also the following flexible VP set operators: 

deallocate-vp-set-processors deallocate-processors-for-vp-set 
set-vp-set-geometry with-processors-allocated-for-vp-set 
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allocated-pvar-p [Function] 

Tests whether a pvar has CM memory allocated for it and, if so, whether it is on the 
stack or the heap. 


Syntax- 

allocated-pvar-p pvar 


Arguments- 

pvar Pvar expression. 


Returned Value- 

allocated-p A symbol. If pvar is allocated, either : stack or :heap is re¬ 

turned, indicating where it is allocated. If pvar is not allocated 
then nil is returned. 

Side Effects- 

None. 


Description- 

This function determines whether or not pvar has CM memory allocated for it. The 
return value of allocated-pvar-p is either : stack, :heap, or nil. If its argument has 
been allocated on the *Lisp stack and has not been deallocated, :stack is returned. 
If its argument has been allocated on the ' Lisp heap and has not been deallocated, 
:heap is returned. Otherwise nil is returned. 
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Examples- 

(allocated-pvar-p (!! 3)) => :stack 
(allocated-pvar-p (allocate!! (!! 3))) => :heap 

(setq x (!! 3)) => #<field-pvar 12-2> 

(*warm-boot) => ni1 
(allocated-pvar-p x) => nil 
(setq y (allocate!! (!! 2))) 

=> #<field-pvar-* allocate!!-return 1336-2> 
(*cold-boot) => 512 
(32 16) 

(allocated-pvar-p y) => nil 


Notes 


References- 

See also the following general pvar information operators: 


describe-pvar 

pvar-exponent-length 


pvar-length 

pvar-locatlon 

pvar-mantissa-length 

pvar-name 

pvarp 

pvar-plist 

pvar-type 

pvar-vp-set 
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alpha-char-p!! [Function] 

Performs a parallel test for alphabetic characters on the supplied pvar. 


Syntax- 

alpha-char-p! ! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for alphabetic characters. 


Returned Value- 

alpha-charp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is 
an alphabetic character. Contains nil in all other active proces¬ 
sors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description-- 

The function alpha-char-p!! is a parallel character predicate. It returns a tempo¬ 
rary pvar containing t in each active processor where the corresponding value of 
character-pvar is an alphabetic character, and nil in all other active processors. The 
function alpha-char-p!! provides the same functionality for character pvars that 
the Common Lisp character predicate alpha-char-p provides for scalar charac¬ 
ters. 


Examples- 

Alphabetic characters are all of the characters between #\A and #\Z, #\a and #\z 
inclusive. The pvar that alpha-char-p!! returns contains t in each processor where 
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the corresponding value of character-pvar is one of these characters. For example, 
if char-pvar contains the values #\A, #\newiine, #\Q, #\z, #\5, #\!, etc., then the 
pvar returned by 

(alpha-char-p!! char-pvar) 

will contain the values t, nil, t, t, nil, nil, etc. 

The function alpha-char-p!! is most useful in combination with the processor se¬ 
lection operators. For example, if text-pvar is a character pvar representing a 
string of text, then 

(*when (alpha-char-p!! text-pvar) 

(*sum (!! 1))) 

returns the number of alphabetic characters in the string. Here, the macro *when 
is used to select only those processors containing an alphabetic character. Then, 
*sum is applied to the constant pvar (!! 1) to return a count of the number of se¬ 
lected processors. 


Notes 


References 
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alphanumericp!! [Function] 

Performs a parallel test for alphanumeric characters on the supplied pvar. 


Syntax- 

alphanumericp!! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for alphanumeric charac¬ 
ters. 


Returned Value- 

alphanumericp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is 
an alphanumeric character. Contains nil in all other active pro¬ 
cessors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function alphanumericp!! is a parallel character predicate. It returns a tempo¬ 
rary pvar containing t in each active processor where the corresponding value of 
character-pvar is an alphabetic or numeric character, and nil in all other active pro¬ 
cessors. Thus, the following forms are equivalent: 

(alphanumericp!! character-pvar) 

<=> 

(or!! (alpha-char-p!! character-pvar) 

(digit-char-p!! character-pvar)) 
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alphanumericp!! 


The function alphanumericp! ! provides the same functionality for character pvars 
that the Common Lisp character predicate alphanumericp provides for scalar 
characters. 


Examples- 

Alphanumeric characters are all of the characters between #\A and #\Z, #\a and 
#\z, and#\0 and #\9 inclusive. The pvar that alphanumericp! ! returns contains t in 
each processor where the corresponding value of character-pvar is one of these 
characters. For example, if char-pvar contains the values #\A, #\newline, #\Q, #\z, 
#\5, #\!, etc., then the pvar returned by 

(alphanumericp!! char-pvar) 

will contain the values t, nil, t, t, t, nil, etc. 

The function alphanumericp!! is most useful in combination with the processor 
selection operators. For example, if text-pvar is a character pvar representing a 
string of text, then 

(*when (alphanumericp!! text-pvar) 

(*sum (!! 1))) 

returns the number of alphanumeric characters in the string. The macro ‘when is 
used to select only those processors containing an alphanumeric character, and 
then ‘sum is applied to the constant pvar (!! 1) to return a count of the number of 
selected processors. 


Notes 


References 
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amap!! [ Function ] 

Maps a function in parallel over a set of array pvars. 


Syntax- 

amap!! operator array-pvar &rest array-pvars 


Arguments- 

operator Parallel function. Must accept the same number of arguments 

as the number of array-pvar arguments supplied. 

array-pvar, array-pvars 

Array pvars. Combined in parallel using operator. 


Returned Value- 

result-pvar Temporary array pvar. In each active processor, contains an 

array whose value in each element is the result of combining 
the corresponding elements of the arrays in the array-pvars us¬ 
ing the specified operator. 

Side Effects- 

The resulting pvar is allocated on the stack. 


Description- 

The amap! ! function maps the supplied operator over the supplied array pvars. The 
operator is applied in turn to each set of elements having the same row-major index 
in the supplied array-pvars. Thus, the / 7 th time function is called, it is applied to a 
list containing the nth element in row-major order from each of the array-pvars. 

The returned array pvar contains in each active processor an array whose value in 
any given element is the result of applying operator to the values of the correspond¬ 
ing elements of the arrays in the supplied array-pvars. 
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The *Lisp function amap!! is similar to the Common Lisp function map, but while 
map works only on vectors, amap!! works on any type of array pvar. The amap!! 
function requires no result type specification, as map does, because the result is 
always returned as an array pvar. 

For vectors, the amap!! function behaves much like the map function in accepting 
vector pvar arguments of different element sizes and in limiting the mapping oper¬ 
ation to the length of the shortest vector pvar supplied. For all other types of array 
pvars, however, amap!! expects the array sizes of the supplied array-pvars to be 
identical. 


Examples- 

The amap!! can be used to emulate vector operators such as the parallel vector 
addition function v+!!. For example, v+!! is equivalent to calling amap!! with an 
operator of ’+!!. Thus: 

(v+!! a b) <==> (amap!! ' + ! ! a b) 

As another example, if y and x are vector pvars of length n, then 

(*set y (amap!! 'log!! (amap!! 'cos!! x))) 

is equivalent to 

(dotimes (j n) 

(*setf (aref!! y (!! j)) 

(log!! (cos!! (aref!! x (!! j)))))) 


Notes 


References- 

Also see the function *map, which behaves somewhat like amap!! but does not 
return a value. 
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*and [* Defun] 

Takes the logical AND of all active values in a pvar, returning a scalar value. 

Syntax- 

•and pvar-expression 

Arguments- 

pvar-expression Pvar expression. Pvar to which global AND is applied. 

Returned Value- 

and-scalar Scalar boolean value. The logical AND of the values in pvar. 

Side Effects- 

None. 

Description- 

The *and function is a global operator. It returns a scalar value of t if the value of 
pvar-expression in every active processor is non-nil, and returns nil otherwise. 

If there are no active processors, this function returns t. 

Examples- 

The function *and can be used to determine whether any value of a pvar fails a 
given predicate. For example, 

(*and (evenp!! numeric-pvar)) 

returns t if every value of numeric-pvar is even, and nil if any value is odd. 
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The following is a simple function definition using *and: 

(*defun *t (pvar) (*and (eql!! pvar t!!))) 

The function *t returns t if and only if its pvar argument is equal to t!!, that is, if it 
contains the value t in every processor. 

The function *and is also useful for determining whether an operation has been 
performed on all values of a pvar. For example, the function defined by 

(defun value-list (pvar) 

(*let ((checked-pvar nil!!)) 

(do ((return-list nil)) 

((*and checked-pvar) return-list) 

(*when (not!! checked-pvar) 

(let ((minumum (*min pvar))) 

(push minimum return-list) 

(*when (=!! pvar (!! minimum))) 

(*set checked-pvar t!!))))))) 

returns a list of the numeric values contained in pvar in all of the currently active 
processors. The variable checked-pvar, initially set to nil!!, indicates which of the 
currently selected processors have already been checked. 

Each time around the do loop, *when is used to select all active processors which 
have not been checked. The minimum value contained in these processors is found 
using *min, and pushed onto return-list. The variable checked-pvar is modified, 
using *set, to indicate that all processors having this value have been checked. 

Each time around the loop, checked-pvar is checked using *and. When (*and 
checked-pvar) returns t, indicating that all of the currently active processors have 
been checked, the loop exits, and return-list, the list of collected values, is returned. 
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Notes 


References- 

See also the related global operators: 

•integer-length *logand 

•logior *logxor 

*min *or 

*xor 

See also the related logical operators: 
and!! not!! or!! 


•max 

•sum 


xor!! 
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and!! [Macro] 

Performs a parallel logical AND operation in all active processors. 


Syntax- 

and!! &rest pvar-exprs 


Arguments- 

pvar-exprs Pvar expressions. Pvars to which parallel AND is applied. 


Returned Value- 

and-pvar Temporary pvar. In each active processor, contains the value 

nil if any of the pvar-exprs evaluate to nil in that processor; con¬ 
tains the value of the last of the pvar-exprs otherwise. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The and!! function performs a parallel logical AND operation. In all active proces¬ 
sors, it evaluates each of the supplied pvar-exprs in order from left to right. As soon 
as one of the pvar-exprs evaluates to nil in a processor, that processor is removed 
from the currently selected set for the remainder of the and!!. 

The temporary pvar returned by and!! contains the value of the last of the pvar- 
exprs in those processors for which each of the previous pvar-exprs evaluated to a 
non-nil value, and nil in all other active processors. If no pvar-exprs are supplied, 
the pvar t!I is returned. 

The function and!! provides functionality for boolean pvars similar to that which 
the Common Lisp function and provides for boolean values. 
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Examples- 

The and!! function can be used either as a straightforward logical operator or as a 
means of controlling evaluation. For example, the pvar returned by 

(and!! (integerp!! numeric-pvar) 

(>=!! numeric-pvar (!! -5)) 

(<=!! numeric-pvar (!! 5))) 

contains t in each active processor for which the value of numeric-pvar is an 
integer between -5 and 5, inclusive, and nil in all other active processors. We could 
add numeric-pvar as the final argument, so: 

(and!! (integerp!! numeric-pvar) 

(>=!! numeric-pvar (!! -5)) 

(<=!! numeric-pvar (!! 5)) 
numeric-pvar) 

This now returns a pvar containing the original value from numeric-pvar in each 
processor where that value is an integer between -5 and 5, and nil in all other active 
processors. 

Because and!! controls the selected set in which its arguments are evaluated, it can 
be used to control evaluation of pvar expressions. The expression 

(if!! (and!!(integerp!! data-pvar) 

(plusp!! data-pvar)) 

(sqrt!! data-pvar)) 

returns a pvar whose value in each active processor is the square-root of the corre¬ 
sponding value of data-pvar, if that value is a positive integer, and nil otherwise. 


Notes- 

Language Note: 

Remember that and! ! changes the currently selected set as it evaluates its argu¬ 
ments. This can have unwanted side effects in code that depends on unchang¬ 
ing selected sets, particularly code involving communication operators, such 
as scan!!. 
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For example, the expressions 

(ppp (and!! (evenp!! (self-address!!)) 

(<!! (scan!! (self-address!!) '+!!) (!! 3))) 

:end 8) 

T NIL T NIL NIL NIL NIL NIL 

(ppp (and!! (<!! (scan!! (self-address!!) ' + !!) (!! 3)) 
(evenp!! (self-address!!))) 

:end 8) 

T NIL NIL NIL NIL NIL NIL NIL 

exemplify a case in which using and!! may cause a non-intuitive result because 
of its deselection properties. In the first expression, the scan!! operation is 
performed only in the even processors. In the second expression, the scan!! 
operation is performed in all processors, resulting in a different set of dis¬ 
played values. 

This is the result of and!! deselecting those processors that fail any clause be¬ 
fore executing the next clause. One can avoid this in the following manner: 

(*let ((bl (evenp!! (self-address!!))) 

(b2 (<!! (scan!! (self-address!!) '+!!) (!! 3)))) 
(declare (type boolean-pvar bl b2)) 

(and!! bl b2)) 


References- 

See also the related global operators: 


and 

•integer-length 

*logand 

logior 

*logxor 

*max 

min 

*or 

*sum 

xor 




See also the related logical operators: 

not!! or!! xor!! 
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•apply [Macro] 

Applies a parallel function defined with * defun to a set of arguments. 


Syntax- 

•apply function &rest args 


Arguments- 

function *Lisp function. Must have been defined using * defun. 

args Set of scalar or pvar values. Arguments to which function is 

applied. Last argument supplied must be a list. 

Returned Value- 

result Scalar or pvar. Result of applying function to the supplied args. 

Side Effects- 

None aside from those produced by function. 


Description- 

This is the parallel equivalent of the Common Lisp apply operator, but is intended 
to be used with functions defined using *defun. Each of the supplied args except 
the last are collected into a list, which is then appended to the last of the orgxThe 
function function is applied to the resulting list. 
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Examples- 

(*defun percent-difference!! (pvarl pvar2) 

(*!! (/!! (-!! pvar2 pvarl) pvarl) (!! 100))) 

(’•'apply 'percent-difference!! 

(!! 2) (list (!! 4))) o> (!! 100.0) 
(♦apply 'percent-difference!! 

(list (!! 5) (!! 2))) <=> (!! -60.0) 


Notes- 

It is an error to use the Common Lisp apply operator with a function defined using 

‘defun. 

It is legal to provide a lambda form as the function argument to ‘apply. However, in 
this case there is no difference between using apply or using ‘apply, and using apply 
is preferred for clarity. 


References- 

See also the following related operations: 

‘defun ‘funcall 

‘trace un*defun ‘untrace 
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aref!! [ Function ] 

Performs a parallel array reference on the supplied array pvar. 


Syntax- 

aref!! array-pvar &rest subscript-pvars 


Arguments- 

array-pvar Array pvar. Pvar from which values are referenced. 

subscript-pvars Integer pvars. Non-negative indices of the array location to be 
referenced in each processor. The number of subscript-pvars 
must equal the rank of array-pvar. 

Returned Value- 

value-pvar Temporary pvar. Value retrieved in each processor. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar on the !|! Lisp stack. The result pvar contains, in each 
processor, a copy of the array-pvar element specified by subscript-pvars. The type 
of the returned pvar is the same as the element type of array-pvar. 

One subscript-pvar argument must be given for each dimension of array-pvar. Each 
subscript-pvar must contain non-negative integers within the legal range of 
coordinates for that dimension. 
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Examples- 

A sample call to aref!! is 

(aref!! 2by5-array-pvar (!! 1) (!! 4)) 

which returns a pvar containing in each processor a copy of the element (1,4) of 
2by5-array-pvar that is stored in that processor. An actual example of an array 
reference is 

(*defvar array-pvar (!! #2A((1 23) (456)))) 

(aref!! array-pvar (!! 0) (!! 2)) <==> (!! 3) 

Here, the element (0,2) of the array-pvar in each processor is 3, so the call to aref!! 
with constant subscript-pvar arguments (pvars having the same value in each pro¬ 
cessor) returns a pvar containing the value 3 in each processor. 

The *setf operator may be used with aref!! to modify array locations in parallel. 
For example, 

(*setf (aref!! array-pvar (!! 0) (!! 2)) (!! 9)) 

The subscript-pvar arguments to aref!! can contain different values in each 
processor. This is known as non-constant array indexing. An example of 
non-constant indexing is 

(♦proclaim "(type (vector-pvar single-float 2) xyzzy)) 

(*defvar xyzzy) 

(defun non-constant-indexing-example () 

(*setf (aref!! xyzzy (!! 0)) (!! 1.0)) 

(*setf (aref!! xyzzy (!! 1)) (!! -1.0)) 

(ppp (aref!! xyzzy 

(if!! (evenp!! (self-address!!)) (!! 0) (!! 1))) 

:end 8)) 

(non-constant-indexing-example) 

1.0 - 1.0 1.0 - 1.0 1.0 - 1.0 1.0 - 1.0 
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Notes 


Performance Note: 

In general, especially for large arrays, the CM-2 implementation of non¬ 
constant indexing can be very slow. See *sideways-array and sideways-aref!! 
for a means of using the CM-2 architecture to do fast non-constant indexing 
into arrays. 


Usage Note: 

In most cases, it is unnecessary to use the operator alias!! in combination with 
aref!! to prevent the copying of pvars, because the *Lisp compiler is able to 
recognize and optimize cases where this copying is unnecessary. 

For example, 

(*proclaim '(type (array-pvar single-float (4)) 
data-array-pvar)) 

(*defvar data-array-pvar (!! #(0.0 1.0 2.0 3.0))) 


(defun bad-example (x) 

(*set (the single-float-pvar x) 

(-*-!! (alias!! (aref!! data-array-pvar (!! 0))) 

(alias!! (aref!! data-array-pvar (!! 1)))))) 

It is unnecessary to use alias! ! to avoid having a copy of the data in elements 0 
and 1 of data-array-pvar being made. As long as the "‘Lisp compiler is 
compiling the code, then 

(defun good-example (x) 

(*set (the single-float-pvar x) 

(+! ! (aref!! data-array-pvar (!! 0)) 

(aref!! data-array-pvar (!! 1))))) 

is equivalent and will not result in any temporary pvars being used. In general 
there is no need to use alias!! when performing array accessing except in 
certain special cases that are discussed under the dictionary entry for alias!!. 
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References-- 

See also the related array-referencing operations: 

row-major-aref!! 

row-major-sideways-aref!! sideways-arefl! 

The following operations convert arrays to and from sideways orientation: 
*processorwise *sideways-array *slicewise 
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array!! [Function] 

Creates and returns an array pvar. In each active processor, an array of the specified 
dimensions is created and initialized with corresponding values from the specified 
pvars. 


Syntax- 

array!! dimensions &rest content-pvars 


Arguments- 

dimensions Integer list. Specifics dimensions of array to store in each 

processor. 

content-pvars Pvars. In each processor, specify, in row-major order, the val¬ 
ues to be stored in that processor’s array. The number of 
content-pvars supplied must match the number of array 
elements specified by dimensions. 

Returned Value- 

array-pvar Temporary array pvar. Contains in each active processor an 

array of the specified dimensions containing the values of the 
content-pvars. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The array! ! function creates an array pvar with the specified dimensions, initialized 
to contain the values of the specified content-pvars. 

The returned array-pvar consists of an a rray i n each active processor. The values of 
each processor’s array elements are copied, in row-major order, from the corre¬ 
sponding values of each supplied content-pvar. 
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Examples- 

(array!! '(2 2) (! ! 0) (!! 1) 

( !! 2) ( ! ! 3)) 

<=> 

(!! #2A((0 1) (2 3))) 


Notes- 

The standard rules of coercion are used to determine the element type of the new 
parallel array. Thus, a mixture of integer and floating-point elements yields a 
floating-point result. A mixture of floating-point and complex elements yields a 
complex result. An error is signaled if the data types present are not all compatible. 
For instance, a string-char element and a floating-point element are not 
compatible. 


References- 

See also the pvar allocation and deallocation operations 

allocate!! 

*deallocate *deallocate-*defvars ‘defvar 

front-end!! ‘let ‘let* 

make-array!! typed-vector!! vector!! 

m 
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*array-dimension [*Defun] 

Returns the length of an array pvar along a specified dimension. 

Syntax- 

‘array-dimension array-pvar dimension 

Arguments- 

array-pvar Array pvar. 

dimension Scalar integer. Index of the dimension for which the length of 

array-pvar is returned. 


Returned Value- 

length Scalar integer. Length of array-pvar along specified dimension. 


Side Effects 

None. 


Description- 

This operation returns an unsigned integer equal to the size of the array-pvar 
dimension referenced by dimension. 

The argument dimension must be an unsigned integer between 0 and Hess than the 
rank of array-pvar. 
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Examples- 

(♦defvar my-array-pvar (array!! '( 21 ) (!! 0) (!! 1))) 

(♦array-dimension my-array-pvar 0) ==> 2 
(♦array-dimension my-array-pvar 1) => 1 


Notes 


References- 

See also the related array pvar information operators: 


array-dimension!! 

"array-dimensions 

"array-element-type 

"array-rank 

"array-total-size 

array-row-major-index!! 


array-dimensions!! 
array-in-bounds-p!! 
array-rank!! 
array-total-size!! 
s i d e ways-a r ray- p 
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array-dimension!! [Function] 

Determines in parallel the length of an array pvar along a specified dimension. 

Syntax- 

array-dimension!! array-pvar dimension-pvar 

Arguments- 

array-pvar 
dimension-pvar 

Returned Value 

length-pvar Temporary integer pvar. Contains in each active processor the 

length of array-pvar along the specified dimension. 

Side Effects- 

Returned pvar is allocated on the stack. 

Description- 

This function returns a pvar containing, in each processor, an unsigned integer 
equal to the length of the dimension-pvar dimension of array-pvar. 

The argument dimension-pvar must be a pvar containing, in each processor, an 
unsigned integer less than the rank of array-pvar. 


Array pvar. 

Integer pvar. In each processor, the array dimension whose 
length is to be returned. 
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Examples- 

(*defvar array-pvar (array!! '(2 1) (!! 0) (!! 1))) 

(ppp (array-dimension!! array-pvar 

(mod!! (self-address!!) (!! 2))) 

rend 12) 

21212121212121 


Notes 


References- 

See also the related array pvar information operators: 

*array-dimension 

*array-dimensions array-dimensions!! 

*array-element-type array-in-bounds-p!! 

*array-rank array-rank!! 

*array-total-size array-totai-size!! 

array-row-major-index!! sideways-array-p 
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"array-dimensions [* Defun] 

Returns list of the lengths of each dimension of an array pvar. 

Syntax- 

‘array-dimensions array—pvar 


Arguments- 

array-pvar Array pvar. 

Returned Value- 

lengths-list Scalar integer list. Lengths of the dimensions of array-pvar. 

Side Effects- 

None. 

Description- 

This operation returns a front-end list enumerating the dimensions of array-pvar. 
This list is of length (*array-rank array-pvar). 
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Examples- 

(♦set my-array-pvar (array!! '(2 1) (!! 0) (!! 1))) 
(♦array-dimensions my-array-pvar) 

-> (2 1 ) 


Notes 


References- 

See also the related array pvar information operators: 

*array-dimen$ion array-dimension!! 

array-dimensions!! 

*array-element-type array-in-bounds-p!! 

*array-rank array-rank!! 

*array-total-size array-total-size!! 

array-row-major-index!! sideways-array-p 
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array-dimensions!! [Function] 

Returns a vector pvar containing the lengths of the dimensions of an array pvar. 


Syntax- 

array-dimensions! ! array-pvar 


Arguments- 

array-pvar Argument type. 


Returned Value- 

lengths-pvar Temporary vector pvar. In each active processor, contains a 
vector enumerating the lengths of the dimensions of array- 
pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a vector pvar containing, in each processor, a vector whose 
nth element is the length of the nth dimension of array-pvar. 
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array-dimensions!! 


Examples- 

(array-dimensions!! (array!! '(2 1) (!! 0) (!! 1))) 
<=> (!! #(2 1)) 


Notes- 

By definition, all arrays in an array pvar have the same size and shape. Thus, the 
pvar returned by array-dimensions! ! will always have the same value in all proces¬ 
sors. 


References 


See also the related array pvar information operators: 


*array-dimension 

*array-dirnensions 

*array-element-type 

*array-rank 

*array-total-size 

array-row-major-index!! 


array-dimension!! 

array-in-bounds-p!! 

array-rank!! 

array-total-size!! 

sideways-array-p 
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*array-element-type [Function] 

Returns type specifier for the elements of an array pvar. 

Syntax- 

*array-element-type array-pvar 

Arguments- 

array-pvar Array pvar. Pvar for which element type is to be returned. 

Returned Value- 

type-spec Type specifier for elements of cirray-pvar. 

Side Effects- 

None. 

Description- 

This function returns a front-end type specifier for the elements of array-pvar. 
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Examples- 

(*array-element-type (array!! '(11) (!! 0))) 
=> (PVAR (UNSIGNED-BYTE 1)) 


Notes 


References- 

See also the related array pvar information operators: 

*array-dimension array-dimension!! 

*array-dimensions array-dimensions!! 

array-in-bounds-p!! 

*array-rank array-rank!! 

* array-total-size array-total-size!! 

array-row-major-index!! sideways-array-p 
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array-in-bounds-p!! [Function] 

Tests in parallel whether array subscripts are within the bounds of an array pvar. 


Syntax- 

array-in-bounds-p!! array-pvar &rest subscript-pvars 


Arguments- 

array-pvar Array pvar. 

subscript-pvars Integer pvars. Subscripts to be checked against bounds of 
array-pvar. 


Returned Value- 

in-boundsp-pvar Temporary boolean pvar. Contains t in every processor where 
the subscript-pvars represent a valid reference to array-pvar. 
Contains nil in all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a boolean pvar with t in every processor where the values of 
the supplied subscript-pvars represent a valid reference to array-pvar and nil else¬ 
where. 
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Examples- 

(♦set my-array-pvar (array!! ' (1 1) (!! 0))) 

(array-in-bounds-p!! my-array-pvar (!! 0) (!! 0)) <=> t!! 
(array-in-bounds-p!! my-array-pvar (!! 2) (!! 0)) <=> nil!! 


Notes 


References- 

See also the related array pvar information operators: 

*array-dimension array-dimension!! 

*array-dimensions array-dimensions!! 

*array-element-type 

*array-rank array-rank!! 

*array-total-size array-total-size!! 

array-row-major-index!! sideways-array-p 

See also the related array-referencing operations: 

aref!! row-major-aref!! 

row-major-sideways-aref!! sideways-aref!! 
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*array-rank [* Defun] 

Returns the number of dimensions of an array pvar. 

Syntax- 

*array-rank array-pvar 

Arguments- 

array-pvar Array pvar. 

Returned Value- 

rank Integer. Number of dimensions of array-pvar. 

Side Effects- 

None 

Description- 

This operation returns an unsigned integer equal to the number of dimensions in 
array-pvar. 
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Examples- 

(* array-rank (array!! '(21) (!! 0) (!! 1))) => 2 


Notes 


References- 

See also the related array pvar information operators: 
*array-dimen$ion array-dimension!! 

*array-dimensions array-dimensions!! 

*array-element-type array-in-bounds-p!! 

array-rank!! 

*array-total-size array-total-size!! 

array-row-major-index!! sideways-array-p 
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array-rank!! [Function] 

Determines in parallel the number of dimensions of an array pvar. 


Syntax- 

array-rank !! array-pvar 


Arguments- 

array-pvar Array pvar. 


Returned Value- 

rank-pvar Temporary integer pvar. Contains in each active processor the 

rank, or number of dimensions, of array-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar containing, in each processor, an unsigned integer 
equal to the number of dimensions in array-pvar. 
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Examples- 

(array-rank!! pvar) <=> (!! (*array-rank pvar)) 


Notes- 

By definition, all arrays in an array pvar have the same size and shape. Thus, the 
pvar returned by array-rank!! has the same value in all processors. 

References- 

See also the related array pvar information operators: 

’array-dimension array-dimension!! 

’array-dimensions array-dimensions!! 

’array-element-type array-in-bounds-p!! 

array-rank!! 

’array-total-size array-total-size!! 

array-row-major-index!! sideways-array-p 
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array-row-major-index!! [Function] 

Converts array subscripts to row major indices in parallel. 


Syntax- 

array-row-major-index!! array-pvar &rest subscript-pvars 


Arguments- 

array-pvar Array pvar. 

subscript-pvars Integer pvars. Must contain subscripts valid for array-pvar. 

Returned Value- 

indices-pvar Temporary integer pvar. In each processor, contains the corre¬ 
sponding row major index in array-pvar for the set of sub¬ 
scripts in the subscript-pvars. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, this function converts the array pvar subscripts contained in 
subscript-pvars into row-major indices for array-pvar. 

The subscript-pvars must contain valid array-pvar subscripts. Each of these &rest 
arguments corresponds to a dimension of array-pvar, they must be given in order, 
starting with dimension 0. The number of subscript-pvars arguments must equal 
the rank of array-pvar. 

In each processor the returned indices-pvar contains a single integer, the row-ma¬ 
jor index of the array element specified by the values of the subscript-pvcirs. This 
pvar of row-major indicies may be used to access the array-pvar via the function 

row-major-aref!!. 
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Examples- 

Consider a two-dimensional array pvar, as defined by 

(*defvar arr!! (!! #2A((10 30) (20 40)))) 

The row-major index of each element in arr!! can be determined as follows: 

(ppp a :end 4) => 0101 
(ppp b :end 4) => 0011 
(ppp (array-row-major-index!! arr!! a b) 

:end 4) =>0213 

That the row-major indices are independant of the contents of the array elements 
can be see by evaluating the expression 

(ppp (aref!! arr!! a b) :end 4) => 10 20 30 40 


Notes 


References 


See also the related array pvar information operators: 


*array-dimension 

*array-dimensions 

*array-element-type 

*array-rank 

*array-total-$ize 

sideways-array-p 


array-dimension!! 

array-dimensions!! 

array-in-bounds-p!! 

array-rank!! 

array-total-size!! 
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array-to-pvar [* Defun] 

In send (cube) address order, copies values from a front-end vector to a pvar. 


Syntax- 

array-to-pvar source-array &optional dest-pvar 
&key :array-offset 

:cube-address-start 

:cube-address-end 

Arguments- 

source-array Front-end vector. Array from which values are copied. 

dest-pvar Pvar. An allocated pvar in any VP set, into which values are 

stored. If not supplied, array-to-pvar creates a temporary pvar 
in the current VP set. 

:array-offset Integer. Offset into source-array of first value to copy. 
Default is 0. 

:cube-address-start 

Send (cube) address. Processor at which copying starts. 
Default is 0. 

:cube-address-end 

Send (cube) address. Processor at which copying ends. 
Default is *number-of-processors-!imit*. 

Returned Value- 

dest-pvar The destination pvar, containing values copied from source- 

array. If a dest-pvar argument is supplied, values are copied 
into it. If not, a temporary pvar is created and returned. 
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Side Effects- 

The contents of source-array, beginning at the element specified by array-offset, are 
copied into dest-pvar. All values of dest-pvar from :cube-address-start to :cube- 
address-end are modified, regardless of the currently selected set. If the dest-pvar 
argument is not supplied, a temporary pvar is allocated on the stack. 


Description- 

This function copies data from source-array to dest-pvar in send-address order. 
The source-array must be one-dimensional. If a dest-pvar is not provided, array-to- 
pvar creates a temporary destination pvar. If a temporary destination pvar is cre¬ 
ated, its value in processors to which array-to-pvar did not write is undefined. 

It is legal for source-array to contain more elements than can be stored in 
dest-pvar. The extra elements are ignored. It is an error, however, for source-array 
to contain fewer elements than are needed to fill dest-pvar. 

This function is especially useful for copying data into the CM. It is much faster 
than setting pvar elements individually using *setf and pref. 


Examples- 

After the following forms are evaluated, 

(*defvar pvar) 

(setq array (make-array *number-of-processors-limit* 

:initial-element 3)) 
(array-to-pvar array pvar) 

The value of pvar is (!! 3). 
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array-to-pvar 


Notes- 

Performance Note: 

This operation is fastest when pvars of a specific non-aggregate type are used, 
slower when general pvars are used, and very slow if aggregate pvars are used. 
The examples below shows how to move aggregate data efficiently into the CM. 

The following expressions define a *defstruct type and create a structure pvar 
of that type. 

(*defstruct foo 

(a 0 :type t :cm-type (pvar (unsigned-byte 32))) 

(b 0.0 :type t :cm-type (pvar single-float)) 

) 

(*proclaim '(type (pvar foo) a-foo-pvar)) 

(*defvar a-foo-pvar) 

In the first example, an array of structure objects of type foo is created on the 
front end, and then copied in one operation to a structure pvar on the CM. This 
method of transferring data is very slow, but is relatively straightforward. 

(defvar a-foo-array 

(make-array *number-of-processors-limit* 

:element-type 'foo)) 

(defun init-a-foo-array () 

(dotimes (j *number-of-processors-limit*) 

(setf (aref a-foo-array j) (make-foo)) 

)) 

(defun move-a-foo-array-data-from-front-end-to-cm () 
(array-to-pvar a-foo-array a-foo-pvar) 

) 

The next example is very fast, although it is somewhat non-intuitive. The 
expressions below create a single front-end structure object, and initialize its 
slots with arrays of values that will form the slot values of the structure pvar on 
the CM. Moving the data to the CM involves a separate array transfer for each 
slot, copying the array of elements for that slot to the structure pvar on the CM. 

;;; create single front-end structure object 
(defvar a-foo (make-foo)) 
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;;; initialize the object's slots with arrays 
;;; instead of single values 
(defun init-a-foo () 

(setf (foo-a a-foo) 

(make-array *number-of-processors-limit* 

•.element-type ' (unsigned-byte 32))) 

(setf (foo-b a-foo) 

(make-array *number-of-processors-limit* 

:element-type 'single-float))) 

;;; perform one array-to-pvar transfer for each slot 
;;; (note use of alias!! to prevent slot copying) 

(defun move-a-foo-data-from-front-end-to-cm () 

(array-to-pvar (foo-a a-foo) 

(alias!! (foo-a!! a-foo-pvar))) 

(array-to-pvar (foo-b a-foo) 

(alias!! (foo-b!! a-foo-pvar)))) 

To summarize, using a single front-end structure object with arrays as slot val¬ 
ues and moving each array separately is much faster than using an array of 
structures and moving the array into the CM in a single operation. 


References- 

See also these related array transfer operations: 

array-to-pvar-grid 

pvar-to-array pvar-to-array-grid 

See also the *Lisp operation pref, which is used to transfer single values from the CM 
to the front end. 

The *Lisp operation *$etf, in combination with pref, is used to transfer a single value 
from the front end to the CM. 
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array-to-pvar-grid [*Defun] 

In grid (NEWS) address order, copies values from a front-end array into a pvar. 


Syntax- 

array-to-pvar-grid source-array &optional dest-pvar 

&key : array-offset 

:grid-start 
:grid-end 


Arguments — 

source-array 


dest-pvar 


: array-offset 


: grid-start 


: grid-end 


Front-end array. Array from which values are copied. Must 
have a rank equal to *number-of-dimensions*. 

Pvar. An allocated pvar into which values are stored. If not 
supplied, array-to-pvar-grid creates a temporary pvar in the 
current VP set. 

Integer list. Set of offsets into source-array indicating first 
value to copy. Default is value of (make-list *number-of- 
dimensions* :initial-element 0). 

Integer list, specifying NEWS (grid) address of processor at 
which copying starts. Default is value of (make-list *number- 
of-dimensions* :initial-element 0). 

Integer list, specifying NEWS (grid) address of processor at 
which copying ends. Default is *current-cm-configuration*. 


Returned Value- 

dest-pvar The destination pvar, containing values copied from source- 

array. If dest-pvar is supplied, values are copied into it. If not, a 
temporary pvar is created and returned. 
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Side Effects- 

The contents of source-array, beginning at the element specified by the :array- 
offset argument, are copied into dest-pvar. All values of dest-pvar specified by the 
:grid-start and : grid-end arguments are modified, regardless of the currently 
selected set. If the dest-pvar argument is not supplied, a temporary pvar of the ap¬ 
propriate size is allocated on the stack. 


Description- 

This function copies data from source-array to dest-pvar in grid (NEWS) address 
order. 

The keyword arguments to :array-offset, :grid-start, and :grid-end must be lists of 
length *number-of-dimensions*. 

The data from source-array, starting with element :array-offset as the upper corner, 
are copied into dest-pvar, with :grid-start and :grid-end specifying the upper and 
lower corners, respectively. The value returned by array-to-pvar-grid is dest-arrciy. 
If dest-pvar is unprovided or nil, array-to-pvar-grid creates a temporary destination 
pvar. If a destination pvar is created, its value in processors to which array-to-pvar- 
grid did not write is undefined. 

It is legal for source-array to contain more or fewer elements than can be stored in 
dest-pvar. Extra elements are ignored, and copying an array with fewer elements 
modifies only a subset of the values of dest-pvar. 


Examples- 

The following expressions select a two-dimensional grid configuration, define a 
two-dimensional front-end array, and then copy a portion of the array into a pvar 
on the CM. 

(*cold-boot :initial-dimensions '(128 128)) 

(defparameter an-array 

(make-array '(5 5) :element-type 'single-float 
:initial-element 0.0)) 

(♦proclaim '(type single-float-pvar grid-pvar)) 

(♦defvar grid-pvar) 
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array-to-pvar-grid 


The following call transfers the 4 x 4 subarray of an-array whose corners are 

(l l) (4 1) 

(1 4) (4 4) 

to the 4x 4 subgrid of grid-pvar whose grid-address corners are 

(2 3) (6 3) 

(2 7) (6 7) 


(array-to-pvar-grid an-array grid-pvar 
:array-offset '(1 1) 

:grid-start '(2 3)) 

Notice that since the dimensions of an-array are (5,5), and copying is specified to 
begin at (1,1), an array of only (4,4) elements is copied. This in turn means that only 
a (4,4) subgrid of values is modified in grid-pvar. 


Notes- 

This function is especially useful for copying image data into the Connection Ma¬ 
chine. It is much faster than setting pvar elements individually with * setf and pref. 


References- 

See also these related array transfer operations: 

array-to-pvar 

pvar-to-array pvar-to-array-grid 

See also the *Lisp operation pref, which is used to transfer single values from the CM 
to the front end. 

The *Lisp operation *setf, in combination with pref, is used to transfer a single value 
from the front end to the CM. 
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*array-total-size [* Defun] 

Returns the total size of each array contained in an array pvar. 

Syntax- 

*array-total-size array-pvar 

Arguments- 

array-pvar Array pvar. 

Returned Value- 

total-size Scalar integer. Total size (product of the lengths of each dimen¬ 

sion) of each array contained in array-pvar. 

Side Effects- 

None. 


Description- 

This operation returns an unsigned integer equal to the total number of array-pvar 
elements contained in each processor. 

Notice that the result is not the total number of array elements in all processors. 
Rather, it is the number of elements in a single processor and this count is the same 
for all processors. 

(*array-total-size array-pvar) 

<=> 

(apply #'* (*array-dimensions array-pvar)) 
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Examples- 

(*array-total-size 

(array!! '(22) (!! 0) (!! 1) (!! 2) (!! 3))) 

=> 4 


Notes 


References- 

See also the related array pvar information operators: 

*array-dimension array-dimension!! 

*array-dimensions array-dimensions!! 

*array-element-type array-in-bounds-p!! 

*array-rank array-rank!! 

array-row-major-index!! array-total-size!! 

sideways-array-p 
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array-total-size!! [Function] 

Returns in parallel the total size of the arrays contained in an array pvar. 

Syntax- 

array-total-size!! array-pvar 

Arguments- 

array-pvar Array pvar. 

Returned Value- 

size-pvar Temporary integer pvar. In each active processor, contains the 

total size (product of the lengths of each dimension) of the cor¬ 
responding value of array-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns, in each processor, an unsigned integer equal to the total 
number of array elements contained in that processor. 

(array-total-size!! array-pvar) 

<=> 

(!! (*array-total-size array-pvar)) 
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Examples 


(array-total-size!! 

(array!! '(2 2) (!! 0) (!! 1) (!! 2) (!! 3))) 

<=> (!! 4) 


Notes- 

By definition, an array pvar consists of one array per processor and each array has 
the same size and shape. Thus, the pvar returned by array-total-size! ! has the same 
value in all processors. 


References- 

See also the related array pvar information operators: 


‘array-dimension 

‘array-dimensions 

‘array-element-type 

‘array-rank 

array-row-major-index!! 
sideways-array-p 


array-dimension!! 
array-dimensions!! 
array-in-bounds-p!! 
array-rank!! 
‘array-total-size 
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ash !! [Function] 

Performs a parallel arithmetic shift of the supplied pvars. 


Syntax- 

ash!! integer-pvar count-pvar 


Arguments- 

integer-pvar Integer pvar. Value to be shifted. 

count-pvar Integer pvar. Number of bits by which to shift—to the left if 

positive, to the right if negative. 


Returned Value- 

shifted-pvar Temporary integer pvar. Contains in each processor the result 
of shifting the corresponding value of integer-pvar the number 
of bit positions specified by count-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The ash! ! function performs a parallel arithmetic shift operation. It returns a tem¬ 
porary pvar that contains in each active processor the result of shifting the corre¬ 
sponding value of integer-pvar the number of bit positions specified by count-pvar. 

The values in integer-pvar are shifted to the left in those processors where count- 
pvar is positive, and to the right where count-pvar is negative. In either case, the 
values from integer-pvar are treated as two’s-complement integers, and the sign bit 
is always preserved. In left shifts, zero bits are added from the right; in right shifts, 
copies of the sign bit are added from the left. 
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The ash!! function provides the same functionality for numeric pvars as the Com¬ 
mon Lisp function ash provides for numeric scalars. 


Examples- 

When the values of count-pvar are positive, the corresponding values of integer- 
pvar are shifted to the left. 


(ash! ! 

(! ! 

2) ( 

! 0)) 

<=> 

(! ! 

2) 

(ash!! 

(! ! 

2) ( 

! D) 

A 

II 

V 

( ! ! 

4) 

(ash! ! 

(! ! 

2) ( 

! 3)) 

<=> 

(! ! 

16) 

(ash! ! 

(! ! 

2) ( 

! 9)) 

A 

II 

V 

( ! ! 

1024) 


When the values of count-pvar are negative, the corresponding values of integer- 
pvar are shifted to the right. 


(ash!! 

(! ! 

2) ( ! 

-D) 

<==> 

( ! 

1) 

(ash!! 

( ! ! 

2) (! 

-2)) 

<=> 

( ! 

0) 

(ash!! 

(! ! 

16) ( ! 

! -3)) 

<=> 

( ! 

2) 

(ash! ! 

( ! ! 

1024) 

(!! -9)) 

<=> 

( ! 

2) 


The argument count-pvar can contain both positive and negative values. For exam¬ 
ple, if shift-pvar contains the values -2, -1, 0, 1, 2, etc., then the pvar returned by 

(ash!! (!! 4) shift-pvar) 

contains the values 1, 2, 4, 8, 16, etc. 


Notes 


References 
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asin!! 


asin!! [Function] 

Takes the arc sine of the supplied pvar. 


Syntax- 

asin!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which the arc sine is calculated. 


Returned Value- 

arc-sine-pvar Temporary numeric pvar. In each active processor, contains 
the arc sine in radians of the corresponding value of numeric- 
pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The asin! ! function calculates the arc sine of numeric-pvar in all active processors. 
It returns a temporary pvar containing in each active processor the arc sine in ra¬ 
dians of the corresponding value of numeric-pvar. 

The asin! ! function provides the same functionality for numeric pvars as the Com¬ 
mon Lisp function asin provides for numeric scalars. 


Examples- 

If numeric-pvar contains non-complex values, asin!! returns the arc sine in each 
active processor. 
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(asin!! (!! 1.0)) <=> (!! 1.5707963) 

If numeric-pvar contains complex values, asin!! returns the complex arc sine in 
each active processor. 

(asin!! (!! #c(1.0 0.0))) <=> (!! #c(l.5707963 0.0)) 


Notes —- 

An error is signalled if the argument numeric-pvar contains integer or floating¬ 
point values of magnitude greater than 1.0 in any active processor. Complex values 
with magnitude greater than 1.0 are allowed. 

An error is signalled if the argument numeric-pvar contains a non-numeric value 
in any active processor. 


References 
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asinh!! 


asinh!! [Function] 

Takes the arc hyperbolic sine of the supplied pvar. 


Syntax- 

asinh!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which arc hyperbolic sine is calculated. 


Returned Value- 

asinh-pvar Temporary numeric pvar. In each active processor, contains 

the arc hyperbolic sine in radians of the corresponding value of 
numeric-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The asinh!! function calculates the arc hyperbolic sine of numeric-pvar in all active 
processors. It returns a temporary pvar containing in each active processor the arc 
hyperbolic sine in radians of the corresponding value of numeric-pvar. 

The asinh!! function provides the same functionality for numeric pvars as the 
Common Lisp function asinh provides for numeric scalars. 
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Examples- 

If numeric-pvar contains non-complex values, asinh!! returns the arc hyperbolic 
sine in each active processor. Thus: 

(asinh!! (!! 11.548740)) <=> (!! 3.1415927) 

If numeric-pvar contains complex values, asinh!! returns the complex arc hyper¬ 
bolic sine in each active processor. For example: 

(asinh!! (!! #c(ll.548740 0.0))) <=> (!! #0(3.1415927 0.0)) 

Notes-- 

An error is signalled if the argument numeric-pvar contains a non-numeric value 
in any active processor. 

References- 
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atari!! 


atan!! [ Function] 

Takes the arc tangent of the supplied pvar(s). 


Syntax- 

atan!! numeric-pvar &optional denominator-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which arc tangent is calculated. 

Numerator of value if denominator-pvar is supplied. 

denominator-pvar Numeric pvar. If supplied, denominator of value. 


Returned Value- 

arc-tangent-pvar Temporary numeric pvar. In each active processor, contains 
the arc tangent in radians of the corresponding values in 
numeric-pvar and (if supplied) denominator-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The atan!! function calculates the arc tangent in all active processors. 

If only one argument is given, atan!! returns a temporary pvar containing in each 
active processor the arc tangent in radians of the corresponding value oi numeric- 
pvar. The argument numeric-pvar may contain either real or complex values in this 
case. 

If two arguments are given, the returned pvar contains in each active processor the 
arc tangent of the quotient of numeric-pvar and denominator-pvar. The numeric- 
pvar and denominator-pvar arguments may not contain complex values in this 
case. The quadrant of the result is determined by the respective signs of the two 
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arguments. The angle returned in each processor is in standard position, with one 
side on the x-axis and the other in the same quadrant as the point defined by 
( numeric-pvar, denominator-pvar ) in that processor. 

The atan !! function provides the same functionality for numeric pvars as the Com¬ 
mon Lisp function atan provides for numeric scalars. 


Examples- 

If numeric-pvar contains non-complex values, atan!! returns the arc tangent in 
each active processor. 


(atan! 

(!! 

1.0)) 


<=> 

( ! ! 

0.7853982) 

(atan! 

(!! 

3) (! ! 

4)) 

<=> 

( ! ! 

0.6435011) 

(atan! ! 

(! ! 

-3) ( ! 

! 4)) 

<=> 

(! ! 

-0.6435011) 

(atan! ! 

(! ! 

3) (!! 

-4)) 

<=> 

( ! ! 

2.4980915) 

(atan! ! 

(! ! 

-3) ( ! 

! -4)) 

<=> 

(! ! 

-2.4980915) 


If numeric-pvar contains complex values, atan!! returns the complex arc tangent in 
each active processor. 

(atan!! (!! #c(0.27175258 1.08392333))) <=> (!! #c(1.00.0)) 


Notes- 

An error is signalled if numeric-pvar and denominator-pvar both contain 0 in any 
active processor, or if either argument contains a non-numeric value in any active 
processor. 


References 


7/C/C 


J- uu 
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atanh!! [Function] 

Takes the arc hyperbolic tangent of the supplied pvar. 


Syntax- 

atanh!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which arc hyperbolic tangent is calcu¬ 
lated. 


Returned Value- 

atanh-pvar Temporary numeric pvar. In each active processor, contains 

the arc hyperbolic tangent in radians of the corresponding val¬ 
ue of numeric-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The atanh!! function calculates the arc hyperbolic tangent of numeric-pvar in all 
active processors. It returns a temporary pvar containing in each active processor 
the arc hyperbolic tangent in radians of the corresponding value of numeric-pvar. 
The atanh!! function provides the same functionality for numeric pvars that the 
Common Lisp function atanh provides for numeric scalars. 


Examples- 

If numeric-pvar contains non-complex values, atanh!! returns the arc hyperbolic 
tangent in each active processor. 
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(atanh!! (!! .1)) <=> (!! 0.10033534) 

If numeric-pvar contains complex values, atanh!! returns the complex arc hyper¬ 
bolic tangent in each active processor. 

(atanh!! (!! #c(0.00.0))) <=> (!! #c(0.00.0)) 


Notes- 

An error is signalled if the argument numeric-pvar contains a non-complex value 
of magnitude greater than or equal to 1 in any active processor. 

An error is signalled if the argument numeric-pvar contains a non-numeric value 
in any active processor. 


References 
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bit!! 


bit!! [Function] 

Selects in parallel a bit at a given location in a bit array pvar. 

Syntax- 

bit!! bit-array-pvar &rest pvcir-indices 

Arguments- 

bit-array-pvar 
pvar-indices 

Returned Value 

bit-pvar Temporary bit pvar. In each processor, contains the bit re¬ 

trieved from the corresponding array of bit-array-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a temporary pvar whose value in each processor is the ele¬ 
ment of the bit-array in bit-array-pvar referenced by pvar-indices. 

For example, 

(*defvar bitarr-pvar (!! #(1 0))) 

(bit!! bitarr-pvar (!! 0)) <=> (!! 1) 

(bit!! bitarr-pvar (!! 1)) <=> (!! 0) 


Bit array pvar. Array from which bit is selected. 

Integer pvars. Must contain valid subscripts for bit-array-pvar. 
Specifies location of bit to return. 
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Examples 


Notes 


References- 

See also these related bit-array pvar operations: 
bit-and!! bit-andcl!! bit-andc2!! 

bit-eqv!! bit—ior!! bit-nand!! bit-nor!! 

bit-not!! bit—orcl!! bit—orc2!! bit-xor!! 

sbit!! 
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bit-and!! 


bit-and !! [ Function] 

Performs a parallel bit-wise AND operation on the supplied bit array pvars. 


Syntax- 

bit-and!! bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1, bit-array-pvar-2 

Bit array pvars. Combined using bit-wise AND. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit array pvar. In each active processor, contains 
the bit-wise AND of the arrays in bit-array-pvar-1 and bit-ar- 
ray-pvar-2. Either an allocated pvar or a temporary, depend¬ 
ing on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 
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It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 

Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 1 0 0))) 

(bit-and!! bitarrl bitarr2) <=> (!! #(1 000)) 


Notes 


References- 

See also these related bit-array pvar operations: 
bit!! bit-andcl!! bit-andc2!! 

bit-eqv!! bit—lor!! bit-nand!! bit—nor!! 

bit—not!! bit—orcl!! bit—orc2!! bit—xor!! 

sbit!! 
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bit-andcl!! 


bit-andcl !! [Function] 

Performs a parallel bit-wise AND operation on the supplied bit array pvars, after tak¬ 
ing the complement of its first argument. 


Syntax- 

bit-andcl!! bit-array-pvar-1 bit-array-pvar-2 Soptional destination 


Arguments- 

bit-array-pvar-1 Bit array pvar. Complemented, then combined with bit-array- 
pvar-2 using bit-wise AND. 

bit-array-pvar-2 Bit array pvars. Combined with the complement of bit-array- 
pvar-1 using bit-wise AND. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the result of combining the complement of bit-array-pvar-1 
with bit-array-pvar-2 using bit-wise AND. Either an allocated 
pvar or a temporary, depending on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 
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I 



Description-- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 

It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(•defvar bitarr2 (!! #(1 1 0 0))) 

(bit-andcl!! bitarrl bitarr2) <=> 

(bit-and (bit-not!! bitarrl) bitarr2) <=> (!! #(0 1 0 0)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit-eqv!! 
bit-not!! 
sbit!! 


bit-and!! 
bit—ior!! 
bit—orcl!! 


bit-andc2!! 

bit-nand!! 

bit-orc2M 


bit—nor!! 
bit—xor!! 


x 
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bit-andc2!! 


bit-andc2!! [Function] 

Performs a parallel bit-wise AND operation on the supplied bit array pvars, after tak¬ 
ing the complement of its second argument. 


Syntax- 

bit-andc2!! bit-cirray-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1 Bit array pvars. Combined with the complement of bit-array- 
pvar-2 using bit-wise AND. 

bit-array-pvar-2 Bit array pvar. Complemented, then combined with bit-array- 
pvar-1 using bit-wise AND. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the result of combining bit-array-pvar-1 with the complement 
of bit-array-pvar-2 using bit-wise AND. Either an allocated 
pvar or a temporary, depending on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 
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Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 

It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 1 0 0))) 

(bit-andc2!! bitarrl bitarr2) <=> 

(bit-and bitarrl (bit-not!! bitarr2)) <=> (!! #(0 0 1 0)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit-eqv!! 

bit-not!! 

sbit!! 


bit-and!! 
bit—ior!! 
bit—orcl!! 


bit-andcl!! 

bit-nand!! 

bit-orc2!! 


bit—nor!! 
bit-xor!! 


176 








*Lisp Dictionary 


bit-eqv!! 


bit-eqv!! [Function] 

Performs a parallel bit-wise equivalence operation on the supplied bit array pvars. 


Syntax- 

bit-eqv!! bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1, bit-array-pvar-2 

Bit array pvars. Combined using bit-wise equivalence. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the result of performing a bit-wise equivalence operation on 
the arrays in bit-array-pvar-1 and bit-array-pvar-2. Either an 
allocated pvar or a temporary, depending on the value of desti¬ 
nation. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 
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It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 1 0 0))) 

(bit-eqv!! bitarrl bitarr2) <=> (!! #(1 0 0 1)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit—and!! 

bit-andcl!! 

bit-andc2!! 

bit—ior!! 

bit-nand!! 

bit—nor!! 


bit-not!! 

bit-orcl!! 

bit-orc2!! 

bit-xor!! 


sbit!! 
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bit—ior!! 


bit-ior!! [Function] 

Performs a parallel bit-wise inclusive OR operation on the supplied bit array pvars. 


Syntax- 

bit-iorl! bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1, bit-array-pvar-2 

Bit array pvars. Combined using bit-wise inclusive OR. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvcir 

Temporary bit-array pvar. In each active processor, contains 
the bit-wise inclusive OR of the arrays in bit-array-pvar-1 and 
bit-array-pvar-2. Either an allocated pvar or a temporary, de¬ 
pending on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 
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It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 1 0 0))) 

(bit-ior!! bitarrl bitarr2) <=> (!! #(1 110)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit-and!! 

bit-andcl!! 

bit-andc2!! 

bit-eqv!! 

bit-nand!! 

bit—nor!! 


bit—not!! 

sbit!! 

bit—orcl!! 

bit—orc2!! 

bit-xor!! 
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bit-nand!! 


bit-nand!! [Function] 

Performs a parallel bit-wise NAND operation on the supplied bit array pvars. 


Syntax- 

bit-nand!! bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1 , bit-array-pvar-2 

Bit array pvars. Combined using bit-wise NAND. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the bit-wise NAND of the arrays in bit-array-pvar-1 and bit-ar¬ 
ray-pvar-2. Either an allocated pvar or a temporary, depend¬ 
ing on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 
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It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1 . 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 1 0 0))) 

(bit-nand!! bitarrl bitarr2) <=> (!! #(0 111)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit-eqv!! 
bit-not!! 
sbit!! 


bit—and!! 
bit—ior!! 
bit-orcl!! 


bit-andcl!! 
bit—nor!! 
bit—orc2!! 


bit-andc2!! 

bit-xor!! 
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bit—nor!! 


bit-nor!! [ Function ] 

Performs a parallel bit-wise NOR operation on the supplied bit array pvars. 


Syntax- 

bit-nor!! bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1 , bit-array-pvar-2 

Bit array pvars. Combined using bit-wise NOR. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the bit-wise NOR of the arrays in bit-array-pvar-1 and bit-ar- 
ray-pvar-2. Either an allocated pvar or a temporary, depend¬ 
ing on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 
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It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1 . 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 1 0 0))) 

(bit-nor!! bitarrl bitarr,2) <=> (!! #(0 0 0 1)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit—and!! 

bit-andcl!! 

bit-andc2!! 

bit-eqv!! 

bit—ior!! 

bit-nand!! 


bit-not!! 

sbit!! 

bit—orcl!! 

bit—orc2!! 

bit—xor!! 
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bit—not!! 


bit—not!! [Function] 

Returns the bitwise complement of the supplied bit array pvar. 

Syntax- 

bit-not!! bit-array-pvar &optional destination 

Arguments- 

bit-array-pvar Bit array pvar. Pvar to be bitwise complemented. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the bit-wise complement of the array in bit-array-pvar-1 . Either 
an allocated pvar or a temporary, depending on the value of 
destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar is destructively modified to contain the result. If des¬ 
tination is a bit array pvar, then destination is destructively modified to contain the 
result. 


Description- 

This function inverts all the bits in bit-array-pvar. The result is a bit array pvar of 
the same rank and dimensions as bit-array-pvar. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
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destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar. 


Examples- 

(*defvar bitarr (!! #(1 0))) 
(bit-not!! bitarr) <=> (!! #(0 1)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit-eqv!! 

bit-orcl!! 


bit—and!! 
bit—ior!! 
bit-orc2M 


bit-andcl!! 
bit-nand!! 
bit—xor!! 


bit-andc2!! 
bit-nor!! 
sbit!! 





*Lisp Dictionary 


bit—orcl!! 


bit—Orel!! [Function] 

Performs a parallel bit-wise OR operation on the supplied bit array pvars, after taking 
the complement of its first argument. 


Syntax- 

bit-orcl!! bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1 Bit array pvar. Complemented, then combined with bit-array- 
pvar-2 using bit-wise OR. 

bit-array-pvar-2 Bit array pvar. Combined with the complement of bit-array- 
pvar-1 using bit-wise OR. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the result of combining the complement of bit-array-pvar-1 
with bit-array-pvar-2 using bit-wise OR. Either an allocated 
pvar or a temporary, depending on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 
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bit—orcl!! 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 

It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 100))) 

(bit-orcl!! bitarrl bitarr2) <=> 

(bit-or!! (bit-not!! bitarrl) bitarr2) <=> (!! #(1 101)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit-eqv!! 
bit-not!! 


bit—and!! 
bit—ior!! 
bit—orc2!! 


bit-andcl!! 
bit-nand!! 
bit—xor!! 


bit-andc2!! 
bit—nor!! 
sbit!! 
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bit-orc2!! [ Function] 

Performs a parallel bit-wise OR operation on the supplied bit array pvars, after taking 
the complement of its second argument. 


Syntax- 

bit-orc2M bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1 Bit array pvar. Combined with the complement of bit-array- 
pvar-2 using bit-wise OR. 

bit-array-pvar-2 Bit array pvars. Complemented, then combined with bit-array- 
pvar-1 using bit-wise OR. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the result of combining bit-array-pvar-1 with the complement 
of bit-array-pvar-2 using bit-wise OR. Either an allocated pvar 
or a temporary, depending on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 


189 



bit—orc2!! 


*Lisp Dictionary 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 

It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1100))) 

(bit-orc2!! bitarrl bitarr2) <=> 

(bit-or!! bitarrl (bit-not!! bitarr2)) <=> (!! #(1 Oil)) 


Notes 


References 


See also these related bit-array pvar operations: 


bit!! 

bit-eqv!! 

bit-not!! 


bit-and!! 
bit—ior!! 
bit—orcl!! 


bit-andcl!! 
bit-nand!! 
bit—xor!! 


bit-andc2!! 
bit—nor!! 
sbit!! 
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bit-xor!! [Function] 

Performs a parallel bit-wise XOR operation on the supplied bit array pvars. 


Syntax- 

bit-xor!! bit-array-pvar-1 bit-array-pvar-2 &optional destination 


Arguments- 

bit-array-pvar-1, bit-array-pvar-2 

Bit array pvars. Combined using bit-wise XOR. 

destination Either the value t, the value nil, or a bit array pvar. Determines 

where the result is stored. Defaults to nil. 


Returned Value- 

bit-array-result-pvar 

Temporary bit-array pvar. In each active processor, contains 
the bit-wise XOR of the arrays in bit-array-pvar-1 and bit-ar¬ 
ray-pvar-2. Either an allocated pvar or a temporary, depend¬ 
ing on the value of destination. 


Side Effects- 

If destination is nil or not supplied, the returned pvar is allocated on the stack. If 
destination is t, bit-array-pvar-1 is destructively modified to contain the result. If 
destination is a bit array pvar, then destination is destructively modified to contain 
the result. 


Description- 

This function performs a logical bit-wise operation on the contents of the first two 
arguments. The result is a bit-array pvar of the same rank and dimensions as 
bit-array-pvar-1 and bit-array-pvar-2. 
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bit-xor!! 


It is an error if both required arguments are not bit-array pvars of identical rank 
and dimensionality. 

If supplied, the optional destination argument must be either t, nil, or a bit array 
pvar with the same rank and dimensions as the bit-array-pvar arguments. It de¬ 
faults to nil. If destination is nil, the operation returns a temporary bit array pvar. If 
destination is a bit-array pvar, the result of the operation is destructively stored in 
that pvar. If destination is t, the result of the operation is destructively stored in 
bit-array-pvar-1. 


Examples- 

(*defvar bitarrl (!! #(1 0 1 0))) 

(*defvar bitarr2 (!! #(1 1 0 0))) 

(bit-xor!! bitarrl bitarr2) <=> (!! #(0 110)) 


Notes 


References- 

bit-andc2!! 
bit-nor!! 
sbit!! 


See also these related bit-array pvar operations: 


bit!! 

bit-eqv!! 
bit—not!! 


bit-and!! 
bit—ior!! 
bit—orcl!! 


bit-andcl!! 
bit-nand!! 
bit—orc2!! 
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boole!! [Function] 

Applies boolean operations in parallel to the supplied integer pvars and returns an 
integer pvar. 

Syntax- 

boole!! op-pvar integer-pvarl integer-pvar2 


Arguments- 

op-pvar Integer pvar. Contains in each processor one of a set of opera¬ 

tion constants, described below, that determine the boolean 
operation performed in that processor. 

integer-pvarl, integer-pvar2 

Integer pvars. Pvars to which the boolean operation in op-pvar 
is applied. 

Returned Value- 

integer-result-pvar Temporary integer pvar. In each processor, contains the result 
of applying the boolean function specified by op-pvar to 
integer-pvarl and integer-pvar2. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

The function boole!! is the parallel equivalent of the Common Lisp boole function. 

In each active processor, the logical operation specified by the value of op-pvar is 
performed on the values contained in integer-pvarl and integer-pvar2. 
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The following Common Lisp integer constants are acceptable as components of 
the op-pvar argument: 


boole-clr 

boole-set 

boole-eqv 

boole-xor 


boole-and 

boole-ior 

boole-nor 

boole-nand 


boole-1 

boole-2 

boole-cl 

boole-c2 


boole-andcl 

boole-andc2 

boole-orcl 

boole-orc2 


Examples- 

A simple call to boole!! is 

(boole!! (!! boole-and) nl n2) 

which performs a boole-and operation in each processor on nl and n2. Note that 
this is equivalent to the expression 

(logand!! nl n2) 

Different logical operations can be performed in different processors. For exam¬ 
ple, to have boole-and execute in all odd processors and boole-ior execute in all 
even processors, use the form 

(boole!! (if!! (oddp!! (self-address!!)) 

(!! boole-and) 

(!! boole-ior)) 

nl n2) 


Notes 


References- 

See the definition of the boole function in Common Lisp: The Language. 


V 
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booleanp!! [Function] 

Performs a parallel test for boolean values on the supplied pvar. 


Syntax- 

booleanp!! value-pvar 


Arguments- 

value-pvar Pvar expression. Pvar to be checked for boolean values. 


Returned Value-- 

booleanp-pvar Temporary boolean pvar. Has the value t in each processor in 
which value-pvar contains either t or nil. Contains nil in all oth¬ 
er active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This predicate returns t in each processor in which value-pvar contains either t or 
nil, and returns nil in every other processor. When using general pvars, this can be 
useful to determine which processors contain boolean values. 

Standard Common Lisp does not have a boolean type. *Lisp defines such a type as 

boolean < = > (member t nil). 


Examples 


(booleanp!! nil!!) => t!! 
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Notes 


References 


See also these related pvar data type predicates: 


characterp!! 

floatp!! 

numberp!! 

typep!! 


complexp!! 

front-end-p!! 

string-char-p!! 


integerp!! 

structurep!! 
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both-case-p!! [Function] 

Performs a parallel test for alphabetic characters which have both uppercase and low¬ 
ercase forms. 


Syntax- 

both-case-p!! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for dual-case characters. 


Returned Value- 

both-casep-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is a 
dual-case character. Contains nil in all other processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This predicate tests the case of the character components of character-pvar. 

The argument character-pvar must be a character pvar, a string-char pvar, or a 
general pvar containing only elements of type character or string-char. 

Where character-pvar contains characters that may be represented in either upper 
or lower case, regardless of their current case, both-case-p! ! returns t. Non- 
Roman fonts, for example, may include alphabetic characters that do not have 
uppercase or lowercase counterparts. 

For each function, the return value is nil in those processors containing character 
data that fails to pass the test criterion. 
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(both-case-p!! 

(! ! 

Ac)) 

A 

II 

V 

t! ! 

(both-case-p!! 

(! ! 

AT)) 

A 

II 

V 

t! ! 

(both-case-p!! 

(! ! 

A3)) 

<=> 

nil! 


Examples - 

Notes- 

References 
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byte!! [Function] 

Creates and returns a byte-specifier pvar suitable as an argument to byte-manipula¬ 
tion functions such as Idb!! and dpb!!. 


Syntax- 

byte!! size-pvar position-pvar 


Arguments- 

size-pvar Integer pvar. Specifies size in bits of byte to be manipulated. 

position-pvar Integer pvar. Specified bit position at which byte starts. 


Returned Value- 

bytespec-pvar Temporary integer pvar. In each active processor, contains a 
byte-specifier integer formed by combining the values of 
size-pvar and position-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function byte. It takes 
two integer pvars representing the size and position of a byte pvar. 

The arguments size-pvar and position-pvar may contain different values in each 
processor. The return value of byte! ! is a byte specifier pvar suitable for use as an 
argument to byte-manipulation functions such as Idb!! and dpb!!. 
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Examples- 

Consider an integer pvar that can be manipulated by one of the byte manipulation 
functions. If this integer pvar is specifed by a size-pvar of (!! 16) and a position- 
pvar of (!! 3), we have, in each processor, a 16-bit byte that starts at bit 3 (zero- 
based). The call to byte!! in this instance is 

(byte!! (!! 16) (!! 3)) 


Notes 


References- 

See also these related byte manipulation operators: 

byte-position!! byte-size!! 

deposit-byte!! deposit-field!! dpb!! 

Idb!! Idb—test!! load-byte!! 

mask-field!! 
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byte-position!! [Function] 

Extracts the byte position component from a byte-specifier pvar. 


Syntax- 

byte-position!! bytespec-pvar 


Arguments- 

bytespec-pvar Byte-specifier pvar, as returned by the function byte!!. The 
byte position component of this byte pvar is extracted. 


Returned Value- 

position-pvar Temporary integer pvar. In each active processor, contains the 
byte position component of the corresponding value of 
bytespec-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function byte-position! ! takes a byte specifier pvar, which is the result of a call 
to byte !!. The integer pvar returned is a copy of the position-pvar originally given as 
an argument to byte!!. Thus: 

(byte-position!! (byte!! size pos)) <=> (!! pos) 
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Examples- 

(byte-position!! (byte!! (!! 16) (!! 3))) <=> (!! 3) 


Notes 


References- 

See also these related byte manipulation operators: 
byte!! byte-size!! 

deposit-byte!! deposit-field!! dpb!! 

Idb!! Idb—test!! load-byte!! 

mask-field!! 
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byte-size!! [Function] 

Extracts the byte size component from a byte-specifier pvar. 


Syntax- 

byte-size!! bytespec-pvar 


Arguments- 

bytespec-pvar Byte-specifier pvar, as returned by the function byte!!. The 
byte size component of this byte pvar is extracted. 


Returned Value- 

size-pvar Temporary integer pvar. In each active processor, contains the 

byte size component of the corresponding value of bytespec- 
pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function byte-size!! takes a byte specifier pvar, which is the result of a call to 
byte!!. The integer pvar returned is a copy of the size-pvar originally given as an 
argument to byte!!. Thus: 

(byte-size!! (byte!! size pos)) <=> (!! size) 
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Examples- 

(byte-position!! (byte!! (!! 16) (!! 3))) <=> (!! 16) 


Notes 


References- 

See also these related byte manipulation operators: 
byte!! byte-position!! 

deposit-byte!! deposit-field!! dpb!! 

Idb!! Idb—test!! load-byte!! 

mask-field!! 
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*case lMacro] 

Evaluates *Lisp forms with the currently selected set bound according to the value of a 
pvar expression. 

Syntax- 

*case value-expression (key-expression-1 &rest body-forms-1) 

( key-expression-2 &rest body-forms-2 ) 

(key-expression-n &rest body-forms-n ) 


Arguments- 

value-expression Pvar expression. Value to compare against key-expression-n in 
each clause. 

key-expression Scalar expression. Evaluated, compared with value-expression. 

Selects processors in which to perform the corresponding 
body-forms. 

body-forms *Lisp forms. Evaluated with the currently selected set 

restricted to those processors in which value-expression is eql 
to key-expression. 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

None aside from those of the individual body-forms. 
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Description- 

The *case macro is the parallel equivalent of the Common Lisp case operation. 
Its usage is similar to that of *cond. 


Examples-— 

When the following forms are evaluated, 

(*defvar result (!! 1)) 

(*case (mod!! (self-address!!) (!! 4)) 

(0 (*set result (!! 0))) 

((1 2) (*set result (self-address!!))) 

(otherwise (*set result (!! -1)))) 

result is bound to a pvar with the values 0, 1, 2, -1, 0, 5, 6, -1, etc. 


Notes- 

Usage Note: 

Forms such as throw, return, return-from, and go may be used to exit an exter¬ 
nal block or looping construct from within a processor selection operator. 
However, doing so will leave the currently selected set in the state it was in at 
the time the non-local exit form is executed. To avoid this, use the *Lisp macro 

with-css-saved. 

See the dictionary entry for with-css-saved for more information. 
Performance Note: 

In the CM-2 implementation of *Lisp, ‘case clauses execute serially, in the 
order in which they are supplied. At any given time, therefore, the number of 
processors active within a ‘case clause is a subset of the currently selected set 
at the time the ‘case form was entered. Providing a large number of clauses to 
‘case (and likewise case!!) therefore results in potentially low overall 
processor utilization. 
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case 


References- 

See also the related operators 


*all 

case!! 

*cond 

cond!! 

*ecase 

ecase!! 

*if 

if!! 

^unless 

*when 

with-css- 

-saved 
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case!! 


case!! [Macro] 

Returns a pvar obtained by evaluating *Lisp forms with the currently selected set 
bound according to the value of a pvar expression. 

Syntax- 

case!! value-expression (key-expression-1 &rest value-forms-1) 

(key-expression-2 &rest value-forms-2 ) 

(key-expression-n &rest value-forms-n ) 


Arguments- 

value-expression Pvar expression. Value to compare against each key-expression 
in each clause. 

key-expression Scalar expression. Evaluated, compared with value-expression. 

Selects processors in which to perform the corresponding 
body-forms. 

value-forms *Lisp forms. Evaluated with the currently selected set 

restricted to those processors in which value-expression is eql 
to key-expression. 

Returned Value- 

case-value-pvar Temporary pvar. In each active processor, contains the value 
returned by value-forms-n if and only if value-expression is eql 
to key-expression-n. 

Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

A parallel version of Common Lisp case, with similar usage to cond!!. If two 
clauses contain the same key, the returned pvar contains the values returned by the 
body forms in the first of the clauses. 


Examples- 

For example, the pvar returned by 

(case!! (mod!! (self-address!!) (!! 4)) 

(0 (! ! 0 )) 

((1 2) (self-address!!)) 

(otherwise (!! -1))) 

contains the values 0, 1, 2, -1, 0, 5, 6, -1, etc. 


Notes- 

Performance Note: 

In the CM-2 implementation of *Lisp, case!! clauses execute serially, in the 
order in which they are supplied. At any given time, therefore, the number of 
processors active within a case!! clause is a subset of the currently selected set 
at the time the case! ! form was entered. Providing a large number of clauses to 
case!! (and likewise "case) therefore results in potentially low overall 
processor utilization. 


References- 

See also the related operators 


•all 

•case 

•cond 

cond!! 

•ecase 

ecase!! 

•if 

if!! 

•unless 

•when 


with-css-saved 


! 

v 
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ceiling!! [Function] 

Performs a parallel ceiling operation on the supplied pvar(s). 

Syntax- 

ceiling!! numeric-pvar & optional divisor-numeric-pvar 

Arguments- 

numeric-pvar Non-complex numeric pvar. Value for which the ceiling is cal¬ 
culated. 

divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di¬ 
vided by divisor-numeric-pvar before the ceiling is taken. 

Returned Value- 

ceiling-pvar Temporary integer pvar. In each active processor, contains the 

ceiling of numeric-pvar, divided by divisor-numeric-pvar if 
supplied. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This is the parallel equivalent of the Common Lisp function ceiling, except that 
only one value—the quotient of the division—is computed and returned. 

Examples- 

(ceiling!! (!! 4.5)) <=> (!! 5) 
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Notes 


References- 

See also these related rounding operations: 
floor!! round!! truncate!! 

See also these related floating-point rounding operations: 

fceiling!! ffloor!! fround!! ftruncate!! 
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char = !! [ Function ] 

Performs a case-sensitive parallel comparison of the supplied character pvars for 
equality. 

Syntax- 

char=!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-sensitive equal¬ 
ity. 

character-pvars Character pvars. Compared in parallel for case-sensitive 
equality. 

Returned Value- 

char-equal-pvar Temporary boolean pvar. Contains the value t in each active 
processor where all of the supplied character-pvar arguments 
contain the same character, case-sensitive. Contains nil in all 
other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

The function char=! ! performs a case-sensitive parallel comparison of the supplied 
character pvars for equality. 
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Examples 


(char=! 

(! 

Ac) ( 

! Ac)) 

<=> 

t! ! 


(char=! 

(! 

Ac) ( 

! AC)) 

A 

II 

V 

nil! ! 


(char=! 

( ! 

Ac) ( 

! A3)) 

A 

II 

V 

nil! ! 


(char=! 

(! 

Ac) ( 

! Az)) 

<=> 

nil! ! 


(char=! 

( ! 

! Ac) ( 

! Ac) ( 

! #\c)) <=> 

t! ! 

(char=! 

( ! 

! Ac) ( 

! Ac) ( 

! #\C) ) <=> 

nil! 

(char=! 

(! 

! Ac) ( 

! AZ) ( 

! #\C)) <=> 

nil! 


Notes- 

References 
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Char/=!! [Function] 

Performs a case-sensitive parallel comparison of the supplied character pvars for 
inequality. 

Syntax- 

char/=!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-sensitive in¬ 
equality. 

character-pvars Character pvars. Compared in parallel for case-sensitive in¬ 
equality. 

Returned Value- 

char-not-equal-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where all of the supplied character-pvar arguments 
contain different characters, case-sensitive. Contains nil in all 
other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function char/=!! performs a case-sensitive parallel comparison of the 
supplied character pvars for inequality. 
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Examples 


(char/=! ! 

(M 

Ac) 

(!! Ac)) 

<=> 

nil! 

(char/=!! 

(! ! 

Ac) 

(! ! AC)) 

<=> 

t! ! 

(char/=! ! 

(! ! 

Ac) 

(! ! A3 )) 

<=> 

t! ! 

(char/=!! 

(! ! 

Ac) 

(!! Az)) 

<=> 

t! ! 


(char=!! (! 

Ac) (M 

Ac) 

( ! ! 

Ac)) 

<=> 

nil! 

(char=!! (! 

Ac) (! ! 

Ac) 

( ! ! 

AC)) 

<=> 

nil! 

(char=!! (! 

! Ac) (! ! 

AZ) 

( ! ! 

AC)) 

<=> 

t! ! 


Notes 


References 
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Char < !! [Function] 

Performs a case-sensitive parallel comparison of the supplied character pvars for 
strictly increasing order. 


Syntax- 

chare!! character-pvar &rest character-pvars 


Arguments-- 

character-pvar Character pvar. Compared in parallel, case-sensitive, for in¬ 
creasing order. 

character-pvars Character pvars. Compared in parallel, case-sensitive, for in¬ 
creasing order. 

Returned Value- 

char-less-than-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-sensitive increasing order. Contains nil in all other active 
processors. 


Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

The function chare! ! performs a case-sensitive parallel comparison of the supplied 
character pvars for strictly increasing order. 
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Examples 


(chare!! 

(! 

Ac) 

(! ! 

Ac)) 

e=> 

nil! ! 

(chare!! 

(! 

Ac) 

(M 

AC)) 

e=> 

nil! ! 

(chare!! 

( ! 

#\c) 

(! ! 

A3)) 

e=> 

nil! ! 

(chare!! 

(! 

Ac) 

(! ! 

Az)) 

e=> 

t! ! 

(chare!! 

(! 

! #\A) 

( ! ! 

AB) ( 

! ! AZ) ) < 


Notes 


References 
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char>!! [Function] 

Performs a case-sensitive parallel comparison of the supplied character pvars for 
strictly decreasing order. 


Syntax- 

char>!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel, case-sensitive, for de¬ 
creasing order. 

character-pvars Character pvars. Compared in parallel, case-sensitive, for de¬ 
creasing order. 

Returned Value- 

char-greater-than-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-sensitive decreasing order. Contains nil in all other active 
processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function char>! ! performs a case-sensitive parallel comparison of the supplied 
character pvars for strictly decreasing order. 
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Examples 


(char>! 

(! 

Ac) ( 

!! Ac)) 

<=> 

nil! ! 

(char>! 

(! 

Ac) ( 

M AC)) 

<=> 

t! ! 

(char>! 

(! 

Ac) ( 

/—v 

CO 

=tfe 

A 

II 

V 

t! ! 

(char>! 

(! 

Ac) ( 

! Az)) 

<=> 

nil! ! 

(char>!! 

(! 

! A*) ( 

! Aj) ( 

! ! #\a) ) < 


Notes 
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I 


References 
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char<=!! 


char< = !! [ Function ] 

Performs a case-sensitive parallel comparison of the supplied character pvars for 
nondecreasing order. 

Syntax- 

char<=!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel, case-sensitive, for non¬ 
decreasing order. 

character-pvars Character pvars. Compared in parallel, case-sensitive, for non¬ 
decreasing order. 

Returned Value- 

char-less-than-or-equal-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-sensitive nondecreasing order. Contains nil in all other ac¬ 
tive processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function char<=!! performs a case-sensitive parallel comparison of the 
supplied character pvars for nondecreasing order. 
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Examples 


(char<=!! 

(M 

#\c) 

(M 

Ac)) 

<=> 

t! ! 

(char<=!! 

(! ! 

Ac) 

(! ! 

AC)) 

<=> 

nil! ! 

(char<=!! 

(! ! 

Ac) 

(! ! 

A3) ) 

<=> 

nil! ! 

(char<=!! 

(! ! 

Ac) 

(! ! 

AD) 

<=> 

t! ! 

(char<=!! 

(! ! 

AD 

(! ! 

AS) 

A 

II 

V 

/•N 

/-N 

m 


Notes- 

References 
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char> =!! [Function] 

Performs a case-sensitive parallel comparison of the supplied character pvars for 
nonincreasing order. 


Syntax- 

char>=!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel, case-sensitive, for non¬ 
increasing order. 

character-pvars Character pvars. Compared in parallel, case-sensitive, for non¬ 
increasing order. 

Returned Value- 

char-greater-than-or-equal-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-sensitive nonincreasing order. Contains nil in all other ac¬ 
tive processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function char>=M performs a case-sensitive parallel comparison of the 
supplied character pvars for nonincreasing order. 
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Examples 


(char>=!! 

(! 

Ac) 

(! 

Ac)) 

<=> 

t! ! 

(char>=!! 

(! 

Ac) 

(! 

AC)) 

<=> 

t! ! 

(char>=!! 

(! 

Ac) 

(! 

A3)) 

<=> 

t! ! 

(char>=!! 

(! 

Ac) 

(! 

Az)) 

<=> 

nil! ! 

(char>=!! 

(! 

! A 5) 

( ! 

! Al) ( 

M 

A 

II 

V 


Notes- 

References 
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character!! [Function] 

Coerces the supplied pvar into a character pvar. 


Syntax- 

character! ! char-or-int-pvar 


Arguments- 

char-or-int-pvar Pvar containing only integer or character values. Pvar to be 
coerced into a character pvar. Must be a pvar of type character, 
string-char, integer, or a general pvar containing only elements 
of these types. 

Returned Value- 

char-pvar Temporary character pvar. In each active processor, contains 

the character equivalent of the corresponding value of char- 
or-int-pvar, or the value nil if coercion could not be performed. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

Type coercion is attempted on the argument char-or-int-pvar. In processors where 
this is successful, the resulting character is returned. In processors where this is 
unsuccessful, character!! returns nil. 

(character!! char-or-int-pvar) 

<=> 

(coerce!! char-or-int-pvar '(pvar character)) 
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Examples 


Notes 


References- 

See also the related character pvar constructor make-char!!. 

See also the related character pvar attribute operators: 

char-bit!! char-bits!! char-code!! 

char-font!! initialize-character set-char-bit!! 
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Characterp!! [Function] 

Performs a parallel test for character values on the supplied pvar. 


Syntax- 

characterp!! pvar 


Arguments- 

pvar Pvar expression. Pvar to be tested for character values. 


Returned Value- 

characterp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where pvar contains a character value. Contains nil 
in all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns t in all active processors where the supplied pvar contains 
character data and nil in all other active processors. 
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Examples- 

(characterp!! (!! #\c)) <=> t!! 
(characterp!! (!! 0)) <=> nil!! 


Notes 


References 


See also these related pvar data type predicates: 


booleanp!! 

complexp!! 


floatp!! 

front-end-p!! 

integerp!! 

numberp!! 

string-char-p!! 

structurep!! 

typep!! 
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char-bit!! [Function] 

Tests the state of a single flag bit of the supplied character pvar. 


Syntax- 

char-bit!! character-pvar bit-name-pvar 


Arguments- 

character-pvar Character pvar. Pvar for which bit selected by bit-name-pvar is 

tested. 

bit-name-pvar Integer pvar. Selects bit to be tested in each active processor. 
Must contain integers in the range 0 to 3 inclusive. 


Returned Value- 

flag-state-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the flag bit named by bit-name-pvar in char¬ 
acter-pvar is set. Contains nil in all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description-- 

This function tests the bit-name-pvar bit setting of character-pvar. 

In those processors where character-pvar contains a character element that has the 
bit-name-pvar bit set, char-bit!! returns t. It returns nil where character-pvar con¬ 
tains a character element that does not have the bit-name-pvar bit set. 

The argument character-pvar must be a character pvar, a string-char pvar, or a 
general pvar containing only character and string-char elements. 
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char-bit!! 


Unlike its Common Lisp analogue, the argument bit-name-pvar must be an inte¬ 
ger pvar (either an unsigned-byte or a signed-byte pvar). The following correspon¬ 
dence holds between legal values for the bit-name-pvar argument and the recom¬ 
mended Common Lisp control-bit constants: 


Common Lisp 

*Lisp 

:control 

(!! 0) 

:meta 

(!! 1) 

:super 

(!! 2) 

-.hyper 

(!! 3) 


For example: 

(char-bit!! (!! #\control-x) (!! 0)) => t!! 


(char-bit!! char-pvar (!! x)) <=> 

(logbitp!! (!! x) (char-bits!! char-pvar)) 


Examples 


Notes 


References- 

See also the related character pvar attribute operators: 
char-bits!! char-code!! 

char-font!! initialize-character set-char-bit!! 
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char-bits! ! [Function] 

Extracts in parallel the bits attribute of a character pvar. 


Syntax- 

char-bits!! character-pvar 


Arguments- 

character-pvar Character pvar. Pvar from which to extract the bits attribute. 


Returned Value- 

char-bits-pvar Temporary integer pvar. In each active processor, contains an 
integer representing the bits attribute of the corresponding val¬ 
ue of character-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar that contains the bits attribute of each character ele¬ 
ment of character-pvar. 

The argument character-pvar must be a character pvar, a string-char pvar, or a 
general pvar containing only character or string-char elements. 

By definition, the font and bits attributes of a string-char pvar are zero. It is always 
the case that: 

(char-bits!! string-char-pvar) <=> (!! 0) 
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Examples 


Notes 


References- 

See also the related character pvar attribute operators: 
char-bit!! char-code!! 

char-font!! initialize-character set-char-bit!! 
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char-code! ! [Function] 

Extracts in parallel the code attribute of a character pvar. 


Syntax- 

char-code!! character-pvar 


Arguments- 

character-pvar Character pvar. Pvar from which to extract the code attribute. 


Returned Value- 

char-code-pvar Temporary integer pvar. In each active processor, contains an 
integer representing the code attribute of the corresponding 
value of character-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar that contains the code attribute of each character ele¬ 
ment of character-pvar. 

The argument character-pvar must be a character pvar, a string-char pvar, or a 
general pvar containing only character or string-char elements. 

(char-code!! #\A) <=> (!! 65) 
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char-code!! 


Examples 


Notes 


References- 

See also the related character pvar attribute operators: 

char-bit!! char-bits!! 

char-font!! initialize-character set-char-bit!! 

See also the related character/integer pvar conversion operators: 
char-int!! code-char!! digit-char!! 

int-char!! 


234 



*Lisp Dictionary 
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Char-downcase!! [Function] 

Converts uppercase alphabetic characters in the supplied pvar to lowercase. 


Syntax- 

char-downcase!! character-pvar 


Arguments- 

character-pvar Character pvar. Pvar containing characters to be converted. 

Must be a pvar of type character or string-char, or a general 
pvar containing only elements of these types. 

Returned Value- 

downcase-pvar Temporary character pvar. In each active processor, contains a 
copy of the corresponding value of character-pvar, with upper¬ 
case characters converted to their lowercase equivalents. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function attempts to convert the case of each character element of character- 
pvar. The returned value is a pvar containing converted characters where possible 
and intact original character values elsewhere. During these case conversions, the 
values of the bits and font attributes are not changed. Notice that only alphabetic 
characters are affected by case conversion. Thus, characters with non-zero bit- 
field values are not changed. 
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Examples 


(char-downcase!! 

(M 

AC)) 

<=> 

( ! ! 

Ac) 

(char-downcase!! 

(M 

#\c)) 

<=> 

(M 

Ac) 

(char-downcase!! 

(! ! 

#\3)) 

<=> 

(! ! 

A3) 


Notes 


References 
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Char-equal!! [Function] 

Performs a case-insensitive parallel comparison of the supplied character pvars for 
equality. 


Syntax- 

char-equal!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-insensitive 
equality. 

character-pvars Character pvars. Compared in parallel for case-insensitive 
equality. 

Returned Value- 

char-equal-pvar Temporary boolean pvar. Contains the value t in each active 
processor where all of the supplied character-pvar arguments 
contain the same character, regardless of case. Contains nil in 
all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function makes a case-insensitive comparison between the character element 
of character-pvar in each processor and the character elements of each of the 
character-pvars in the same processor. Differences in case, bit, and font attributes 
are ignored. 

A boolean pvar is returned. It contains t in all active processors where the test is 
true and nil in all active processors where the test is false. 
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The argument character-pvar and each of the optional character-pvars must be a 
character pvar, a string-char pvar, or a general pvar containing only character or 
string-char elements. 


Examples 


(char-equal!! 

(!! #\c) 

(! ! Ac)) 

<=> 

t! ! 

(char-equal!! 

(!! #\C) 

(! ! AC)) 

<=> 

t! ! 

(char-equal!! 

(!! Ac) 

(! ! A3)) 

<=> 

nil! 

(char-equal!! 

(!! Ac) 

(! ! Az)) 

A 

II 

V 

nil! 


Notes 


References 
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Char-flipcase!! [Function] 

In the supplied pvar, converts uppercase characters to lowercase, and vice-versa. 


Syntax- 

char-flipcase!! character-pvar 


Arguments- 

character-pvar Character pvar. Pvar containing characters to be converted. 

Must be a pvar of type character or string-char, or a general 
pvar containing only elements of these types. 


Returned Value-- 

downcase-pvar Temporary character pvar. In each active processor, contains a 
copy of the corresponding value of character-pvar, with upper¬ 
case characters converted to lowercase, and lowercase charac¬ 
ters converted to uppercase. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function attempts to invert the case of each character element of character- 
pvar. The return value is a pvar containing converted characters where possible 
and intact original character values elsewhere. During these case conversions, the 
values of the bits and font attributes are not changed. Notice that only alphabetic 
characters are affected by case conversion. Thus, characters with non-zero bit field 
values are not changed. 
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Examples 


(char-flipcase!! 

(! 

#\C)) 

<=> 

(! 

Ac) 

(char-flipcase! ! 

( ! 

Ac)) 

<=> 

( ! 

AC) 

(char-flipcase!! 

(! 

A3)) 

<=> 

(! 

A3) 


Notes- 

References 
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char-font! ! [Function] 

Extracts in parallel the font attribute of a character pvar. 


Syntax- 

char-font!! character-pvar 


Arguments- 

character-pvar Character pvar. Pvar from which to extract the font attribute. 

Must be a character pvar, a string-char pvar, or a general pvar 
containing only character or string-char elements. 

Returned Value- 

font-pvar Temporary integer pvar. In each active processor, contains a 

integer representing the font attribute of the corresponding 
value of character-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar that contains the font attributes of each character 
element of character-pvar. 
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char-font!! 


Examples 


Notes- 

By definition, the font and bits attributes of a string-char pvar are zero. Thus, it is 
always the case that: 

(char-font!! string-char-pvar) <=> (!! 0) 


References- 

For a discussion of Common Lisp character attributes (code, bits, and font), see 
Common Lisp: The Language, Chapter 13. 

See also the related character pvar attribute operators: 

char-bit!! char-bits!! char-code!! 

initialize-character set-char-bit!! 
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char-greaterp!! [Function] 

Performs a case-insensitive parallel comparison of the supplied character pvars for 
decreasing order. 


Syntax- 

char-greaterp!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-insensitive 
decreasing order. 

character-pvars Character pvars. Compared in parallel for case-insensitive 
decreasing order. 

Returned Value- 

char-greaterp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-insensitive decreasing order. Contains nil in all other ac¬ 
tive processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function makes a case-insensitive comparison between the character element 
of character-pvar in each processor and the character elements of each of the 
character-pvars in the same processor. Differences in case, bit, and font attributes 
are ignored. 

A boolean pvar is returned. It contains t in all active processors where the test is 
true and nil in all active processors where the test is false. 
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The argument character-pvar and each of the optional character-pvars must be a 
character pvar, a string-char pvar, or a general pvar containing only character or 
string-char elements. 


Examples 


(char-greaterp!! (!! #\Z) (!! #\N) (!! #\A)) <=> t!! 

(char-greaterp!! (!! #\Z) (!! #\z)) <=> nil!! 


Notes 


References 
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Char-int!! [Function] 

Converts the supplied character pvar into an integer pvar. 


Syntax- 

char-int!! character-pvar 


Arguments- 

character-pvar Character pvar. Pvar to be converted. Must be a pvar of type 
character or string-char, or a general pvar containing only ele¬ 
ments of these types. 


Returned Value- 

integer-pvar Temporary integer pvar. In each active processor, contains the 

integer value of the character in character-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function translates a character pvar into an integer pvar. 

The return value is a non-negative integer pvar that holds the implementation-de- 
pendent encoding of each character in character-pvar. 
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char-int!! 


Examples 


(char-int!! (!! #\A)) <=> (!! 65) 


Notes- 

The char-int!! function relies on the Connection Machine system’s encoding of 
characters. Results obtained from this function should not be expected to conform 
to results obtained from the Common Lisp function char-int run on front-end 
machines. 


References- 

See also the related character/integer pvar conversion operators: 

char-code!! code-char!! digit-char!! 

int-char!! 
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char-lessp!! [Function] 

Performs a case-insensitive parallel comparison of the supplied character pvars for 
increasing order. 


Syntax- 

char-lessp!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-insensitive 
increasing order. 

character-pvars Character pvars. Compared in parallel for case-insensitive 
increasing order. 

Returned Value- 

char-greaterp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-insensitive increasing order. Contains nil in all other ac¬ 
tive processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function makes case-insensitive comparisons between the character element 
of character-pvar in each processor and the character elements of each of the 
character-pvars in the same processor. Differences in case, bit, and font attributes 
are ignored. 

A boolean pvar is returned. It contains t in all active processors where the test is 
true and nil in all active processors where the test is false. 
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The argument character-pvar and each of the optional character-pvars must be a 
character pvar, a string-char pvar, or a general pvar containing only character or 
string-char elements. 


Examples 


(char-lessp!! (!! #\A) (!! #\N) (!! #\Z)) <=> t!! 

(char-lessp!! (!! #\ Z) (!! #\z)) <=> nil!! 


Notes 


References 
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char-not-equal!! [Function] 

Performs a case-insensitive parallel comparison of the supplied character pvars for 
inequality. 


Syntax- 

char-not-equal!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-insensitive in¬ 
equality. 

character-pvars Character pvars. Compared in parallel for case-insensitive in¬ 
equality. 

Returned Value- 

char-equal-pvar Temporary boolean pvar. Contains the value t in each active 
processor where all of the supplied character-pvar arguments 
contain different characters, case-insensitive. Contains nil in 
all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function makes case-insensitive comparisons between the character element 
of character-pvar in each processor and the character elements of each of the 
character-pvars in the same processor. Differences in case, bit, and font attributes 
are ignored. 

A boolean pvar is returned. It contains t in all active processors where the test is 
true and nil in all active processors where the test is false. 


249 



*Lisp Dictionary 


char-not-equal!! 


The argument character-pvar and each of the optional character-pvars must be a 
character pvar, a string-char pvar, or a general pvar containing only character or 
string-char elements. 


Examples 


(char-not-equal!! ( 

! #\c) ( 

! Ac)) 

<=> 

nil! 

(char-not-equal!! ( 

! Ac) ( 

! AC)) 

<=> 

nil! 

(char-not-equal!! ( 

! Ac) ( 

! A3)) 

<=> 

t! ! 

(char-not-equal!! ( 

! Ac) ( 

! Az)) 

<=> 

t! ! 


Notes 


References 
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char-not-greaterp!! [Function] 

Performs a case-insensitive parallel comparison of the supplied character pvars for 
nondecreasing order. 


Syntax- 

char-not-greaterp!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-insensitive non¬ 
decreasing order. 

character-pvars Character pvars. Compared in parallel for case-insensitive 
nondecreasing order. 

Returned Value- 

char-not-greaterp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-insensitive nondecreasing order. Contains nil in all other 
active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function makes case-insensitive comparisons between the character element 
of character-pvar in each processor and the character elements of each of the 
character-pvars in the same processor. Differences in case, bit, and font attributes 
are ignored. 

A boolean pvar is returned. It contains t in all active processors where the test is 
true and nil in all active processors where the test is false. 


251 



char-not-greaterp!! 


*Lisp Dictionary 


The argument character-pvar and each of the optional character-pvars must be a 
character pvar, a string-char pvar, or a general pvar containing only character or 
string-char elements. 


Examples 


(char-not-greaterp!! (!! #\Z) (!! #\N) (!! #\A)) <=> nil!! 

(char-not-greaterp!! (!! #\Z) (!! #\z)) <=> t!! 


Notes 


References 
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char-not-lessp!! [Function] 

Performs a case-insensitive parallel comparison of the supplied character pvars for 
nonincreasing order. 


Syntax- 

char-not-lessp!! character-pvar &rest character-pvars 


Arguments- 

character-pvar Character pvar. Compared in parallel for case-insensitive non¬ 

increasing order. 

character-pvars Character pvars. Compared in parallel for case-insensitive 
nonincreasing order. 

Returned Value- 

char-not-greaterp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the supplied character-pvar arguments are in 
case-insensitive nonincreasing order. Contains nil in all other 
active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function makes case-insensitive comparisons between the character element 
of character-pvar in each processor and the character elements of each of the 
character-pvars in the same processor. Differences in case, bit, and font attributes 
are ignored. 

A boolean pvar is returned. It contains t in all active processors where the test is 
true and nil in all active processors where the test is false. 
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The argument character-pvar and each of the optional character-pvars must be a 
character pvar, a string-char pvar, or a general pvar containing only character or 
string-char elements. 

Examples- 

(char-not-lessp!! (!! #\A) (!! #\N) (!! #\Z)) <=> t! ! 

(char-not-lessp!! (!! #\Z) (!! #\z)) <=> nil!! 

Notes- 

References- 
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char-upcase!! [Function] 

Converts lowercase alphabetic characters in the supplied pvar to uppercase. 


Syntax- 

char-upcase !! character-pvar 


Arguments- 

character-pvar Character pvar. Pvar containing characters to be converted. 

Must be a pvar of type character or string-char, or a general 
pvar containing only elements of these types. 


Returned Value- 

upcase-pvar Temporary character pvar. In each active processor, contains a 

copy of the corresponding value of character-pvar, with lower¬ 
case characters converted into their uppercase equivalents. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function attempts to convert the case of each character element of character- 
pvar. The return value is a pvar containing converted characters where possible 
and intact original character values elsewhere. During these case conversions, the 
values of the bits and font attributes are not changed. Notice that only alphabetic 
characters are affected by case conversion. Thus, characters with non-zero bit field 
values are not changed. 


255 






*Lisp Dictionary 


char-upcase!! 


Examples 


(char-upcase!! 

(M AC)) 

<=> 

(! ! 

AC) 

(char-upcase!! 

(! ! Ac)) 

A 

II 

V 

(! ! 

AC) 

(char-upcase!! 

(M A3)) 

<=> 

(! ! 

A3) 


Notes- 

References 
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Cis!! [Function] 

Performs a parallel conversion of phase angles into unit-length complex numbers. 


Syntax- 

cis!! numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Phase angle in radians to convert 
to a complex number. 


Returned Value- 

cos-i-sin-pvar Temporary complex pvar. In each active processor, contains a 
unit-length complex number with a phase angle equal to the 
corresponding value of numeric-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function cis. It returns 
a temporary complex pvar whose value in each processor is a complex number of 
unit length, whose phase is the value of the corresponding value of numeric-pvar. 

(cis!! (!! 3.1415927)) <=> (!! #c (-1.0 2.3841858e-7)) 

Another way to view this function is as returning the position on a unit circle, cen¬ 
tered on the complex plane, that corresponds to the angle stored in each processor 
of a pvar (see Figure 1). 
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imaginary axis 



(cis!! (!! angle)) <=> (!! #c( a b )) 


Figure 1. The function cisl! calculates positions on a unit circle 
centered in the complex plane. 


Examples 


Notes 


References- 

See also these related complex pvar operators: 


abs!! 

complex!! 


conjugate!! 

realpart!! 

imagpart!! 

phase!! 
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code-char! ! [Function] 

Converts numeric pvar of character codes to a character pvar with the supplied 
attributes. 


Syntax- 

code-char!! code-pvar &optional bits-pvar font-pvar 


Arguments- 

code-pvar Non-negative integer pvar. Code attribute of character pvar. 

bits-pvar Non-negative integer pvar. Bits attribute of character pvar. 

font-pvar Non-negative integer pvar. Font attribute of character pvar. 


Returned Value- 

char-pvar Temporary character pvar. In each active processor, contains a 

character with the code, bits, and font attributes specified by 
the corresponding values of code-pvar, bits-pvar, and font- 
pvar. Contains nil in processors where the specified character 
can not be constructed. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function attempts to construct a character pvar with the specified attributes. 
In processors where this can be done, the resulting character is returned. In proc¬ 
essors where this can not be done, nil is returned. 

All three arguments must be non-negative integer pvars. The optional bits-pvar 
argument and the optional font-pvar argument each default to (!! 0). 
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Examples- 

(code-char!! (!! 65)) <=> (!! #\A) 


Notes 


References- 

For a discussion of Common Lisp character attributes (code, bits, and font), see 
Common Lisp: The Language, Chapter 13. 

See also the related character pvar attribute operators: 

char-bit!! char-bits!! char-code!! 

char-font!! initialize-character set-char-bit!! 

See also the related character/integer pvar conversion operators: 
char-code!! char-int!! digit-char!! 

int-char!! 
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coerce !! [Function] 

Performs a parallel type coercion on the supplied pvar. 


Syntax- 

coerce!! pvar type-spec 


Arguments- 

pvar Pvar expression. Pvar containing values to be coerced. 

type-spec Type specifier. Must specify a valid *Lisp pvar type. 

Returned Value- 

coerced-pvar Temporary pvar. Result of coercing pvar to the pvar type sped 

fied by type-spec. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The coerce!! function is the parallel equivalent of the Common Lisp coerce func- 
tion.This function attempts to convert pvar to the type indicated by type-spec. If 
this is possible, the result is returned as a new pvar allocated on the *Lisp stack. If 
pvar is already of type type-spec, a copy of pvar is returned. If the specified conver¬ 
sion is not possible, an error is signaled. 

Important: in many simple cases, type conversion is performed automatically. For 
example, arithmetic operations such as +!! and pvar copying functions such as *set 
automatically coerce their arguments according to the rules of *Lisp type coercion. 
It is only necessary to explicitly coerce! ! a pvar in special cases, such as converting 
a numeric pvar to a larger bit size or altering the element type of an array pvar. 
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coerce!! 


Examples- 

It is not generally possible to convert a given pvar to any data type; only certain 
conversions are permitted: 

■ An integer pvar (a signed-byte or unsigned-byte pvar) may be converted 
to an integer pvar type of a different byte size. For instance, a pvar of type 
(pvar (unsigned-byte 8)) may be coerced to (pvar (signed-byte 16)) 

(♦proclaim '(type (pvar (unsigned-byte 8)) data-8)) 
(*defvar data-8 (random!! (!! 20))) 

(♦proclaim '(type (pvar (unsigned-byte 16)) data-16)) 
(♦defvar data-16) 

(♦set data-16 

(coerce!! data-8 '(pvar (signed-byte 16)))) 

Conversions to smaller byte sizes are also legal. For example, a pvar of type 
(pvar (unsigned-byte 8)) may be coerced to (pvar (unsigned-byte 4)) 

(♦proclaim '(type (pvar (unsigned-byte 4)) data-4)) 
(♦defvar data-4 (random!! (!! 4))) 

(♦set data-4 (coerce!! data-8 '(pvar (signed-byte 4)))) 

■ Integer pvars may be converted to floating-point pvar types. For example, a 
pvar of type (unsigned-byte-pvar 16) may be converted to a pvar of type 
(pvar single-float) 

(♦proclaim '(type single-float-pvar data-sf)) 

(♦defvar data-sf) 

(♦set data-sf (coerce!! data-16 '(pvar single-float))) 


■ A floating-point pvar may be converted to a floating-point pvar of a differ¬ 
ent size. For instance, a pvar of type (pvar single-float) may be coerced to a 
pvar of type (pvar double-float) 

(♦proclaim '(type double-float-pvar data-df)) 

(♦defvar data-df) 


4* \J 4* 


(♦set data-df (coerce!! data-sf '(pvar double-float))) 
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■ An integer pvar or a floating-point pvar may be converted to a complex 
pvar. For example, a single-float pvar can be converted to a complex pvar 
for which both exponent and significand are of type double-float 

(♦proclaim '(type double-complex-pvar data-df-complex)) 
(*defvar data-df-complex) 

(♦set data-df-complex 

(coerce!! data-sf 'double-complex-pvar)) 


■ A complex pvar may be converted to a complex pvar of a different size. 
Thus, a pvar of type single-complex-pvar can be converted to a pvar of 
type double-complex-pvar 

(♦proclaim '(type single-complex-pvar data-sf-complex)) 
(♦defvar data-sf-complex (complex!! (!! 1.0) (!! -1.0))) 

(♦set data-df-complex 

(coerce!! data-sf-complex 'double-complex-pvar)) 


■ An integer pvar may be converted to a character pvar. This conversion is 
identical to that performed by the function int-char!! 

(♦proclaim '(type character-pvar data-char)) 

(♦defvar data-char) 

(♦set data-char 

(coerce!! (random!! (!! 65)) 'character-pvar)) 

■ A string-char array pvar of length 1 may be converted to a character pvar. 

(♦proclaim '(type (pvar (array string-char (1))) 
data-string-char)) 

(♦defvar data-string-char (!! "C")) 

(♦set data-char 

(coerce!! data-string-char 'character-pvar)) 
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■ Any pvar, except an array or a structure pvar. may be converted to a gen¬ 
eral pvar. 

(♦proclaim '(type (pvar front-end) data-front-end)) 
(*defvar data-front-end (front-end!! 'commander)) 
(♦proclaim '(type (pvar t) data-general)) 

(♦defvar data-general) 

(♦set data-general (coerce!! data-front-end '(pvar t))) 

■ An array pvar’s element type may be converted in accordance with the per¬ 
mitted conversions mentioned above. For instance, an array pvar with ele¬ 
ments of type single-float may be coerced to an array pvar with elements of 
type double-float. 

(♦proclaim '(type (pvar (array single-float (20))) 
data-array-sf)) 

(♦defvar data-array-sf 

(make-array!! '(20) 

:initial-element (random!! (!! 2.0)) 

:element-type 'single-float)) 

(♦proclaim '(type (pvar (array double-float (20))) 
data-array-df)) 

(♦defvar data-array-df) 

(♦set data-array-df (coerce!! data-array-sf 

'(pvar (array double-float (20))))) 
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Notes- 

Explicit type conversion functions may be used in place of coerce!!. 

Examples of *Lisp functions in this category are: 

ceiling!! character!! complex!! 

float!! floor!! round!! 

truncate!! 


References- 

See also the related *Lisp declaration operators: 

"locally *proclaim unproclaim 

See also the related type translation function taken-as!!. 
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*COld-bOOt [Macro] 

Initializes *Lisp, resets the Connection Machine hardware, and defines the current 
machine configuration and default VP set. 


Syntax 


*cold-boot &key -.safety 

: initial-dimensions 
: initial-geometry-definition 
:undefine-all 


Arguments- 

: safety An integer between 0 and 3, inclusive. Specifies a value for the 

*Lisp variable ‘interpreter-safety*. Defaults to 3, the highest 
safety level. 


: initial-dimensions 

A list of integers, each of which must be a power of 2. Defines 
the dimensions of the *default-vp-set*. Defaults to a two- 
dimensional grid with a VP ratio of 1. 

: initial-geometry-definition 

Geometry object, as returned by create-geometry. May be 
supplied instead of an : initial-dimensions argument to define 
the geometry of the *default-vp-set*. 

:undefine-all Boolean value. Determines whether currently defined VP sets 
and permanent pvars are reallocated. Defaults to nil, indicat¬ 
ing that VP sets and permanent pvars should be reallocated. 


Returned Values- 

physical-size The value of *minimum-size-for-vp-set*, equal to the num¬ 
ber of physical processors attached. 

dimensions The value of *current-cm-configuration*, a list of integers de¬ 

fining the geometry of the *default-vp-set*. 
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Side Effects- 

Initializes *Lisp and Connection Machine hardware. If :undefine-all is nil, 
reallocates permanent pvars and VP sets. Attempts to attach to CM hardware if 
not already attached. 


Description- 

The * cold-boot macro initializes the *Lisp system and resets the Connection Ma¬ 
chine hardware. It should be called immediately after loading in the *Lisp software 
and attaching to a Connection Machine, and before executing *Lisp code that does 
anything other than defining pvars (with *defvar) and defining VP sets. The 'cold- 
boot macro may also be called from top level at any time to change the processor 
configuration of the Connection Machine. 

In general, * cold-boot should be called only from top level or at the very beginning 
of the main function of a program. It should never be called at any other point in a 
program, because it resets the entire state of *Lisp and the Connection Machine. 

The : safety keyword argument specifies a value for the *Lisp global variable 
'interpreter-safety*. See the description of 'interpreter-safety* in Chapter 2, 
“*Lisp Global Variables”, for a description of interpreter safety levels. 

The keyword arguments : initial-dimensions and : initial-geometry-definition 
specify the geometry of the initial VP set bound to the *Lisp global variable 
*default-vp-set*. One or the other but not both of these keyword arguments may 
be provided. 

The: initial-dimensions keyword argument specifies the dimensions of the Connec¬ 
tion Machine processor configuration. For example, an : initial-dimensions argu¬ 
ment of (32 16 64) specifies a three-dimensional processor configuration with 
dimensions 32 x 16 x 64. The dimensions must be powers of 2. The product of the 
dimensions must be either equal to the number of physical processors attached, or 
equal to a power of two multiple of the number of attached processors. 

The : initial-geometry-definition allows the use of a geometry object to specify the 
processor configuration. Supplying a geometry object instead of a list of dimen¬ 
sions permits greater control over the routing pattern and processor address 
mapping of the default VP set. See the definition of create-geometry for more in¬ 
formation about creating and using geometry objects. 













*Lisp Dictionary 


‘cold-boot 


If neither the : initial-dimensions nor the: initial-geometry-definition arguments is 
supplied, the dimensions default to the same configuration as that used in the pre¬ 
vious call to *cold-boot. If there was no previous call, the default is a two- 
dimensional grid with a VP ratio of 1. 

The :undefine-all keyword determines whether all permanent VP sets and perma¬ 
nent pvars are reallocated. If: undef ine-all is nil, the default, all permanent VP sets 
and permanent pvars are automatically reallocated. If this argument is non-nil, 
*cold-boot deallocates and destroys all permanent pvars and all VP sets with the 
exception of the *default-vp-set* and its associated geometry object. 

In detail, calling ‘cold-boot performs the following operations in sequence: 

■ evaluates in order the forms on the * before-‘cold-boot-initializations* list 

■ deallocates all previously defined pvars, including permanent pvars 

■ deallocates all previously defined VP sets 

■ attempts to attach to Connection Machine hardware—if not already atta¬ 
ched—and calls the Paris function cm:cold-boot if successful 

■ sets the value of the variable ‘interpreter-safety* 

■ instantiates the VP set bound to *defau!t-vp-set* with a geometry based 
on the values of the : initial-dimensions and : initial-geometry-definition 
arguments 

■ if: undef ine-all is nil, redefines all permanent VP sets in an arbitrary order, 
and instantiates all fixed-size VP sets 

■ if : undef ine-all is nil, reallocates and reinitializes, using ‘defvar, perma¬ 
nent pvars that belong to instantiated VP sets 

■ selects the VP set *default-vp-set‘, making it the *current-vp-set* 

■ evaluates in order the forms on the *after-*cold-boot-initializations* list 
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Examples- 

Here are some sample calls to *cold-boot, defining various configurations of pro¬ 
cessors. 

(♦cold-boot :initial-dimensions '(64 64)) 

(♦cold-boot -.initial-dimensions '(64 64 32)) 

(♦cold-boot .-initial-dimensions '(2 2222222222 2)) 

Here is a sample call to * cold-boot using a geometry object to define the processor 
configuration. 


(defvar my-geometry 

(create-geometry :dimensions '(2 32 2) :weights '(2 1 3))) 
(♦cold-boot :initial-geometry-definition my-geometry) 

The next two examples assume that a Connection Machine with 8K processors is 
attached, and that no previous call to ’"cold-boot has been made. The first example 
defines a configuration with a VP ratio of 1, i.e., one virtual processor for each 
physical processor. Because no dimensions are supplied, a 2-dimensional grid of 
processors is defined, with dimensions 64 by 128. 

(♦cold-boot) ;8k physical processors 

8192 

(64 128) 

The second example defines a configuration with a VP ratio of 2, i.e., twice as many 
virtual processors as physical processors. 

(♦cold-boot 

:initial-dimensions '(128 128)) ;16k virtual processors 

8192 

(128 128) 

Notice that the user does not specify the VP ratio explicitly. As long as the 
dimensions specified are equal to either the number of physical processors 
attached, or to a power-of-two multiple of the number of attached processors, the 
proper VP ratio will be determined automatically and transparently. 
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Notes- 

Style Note: 

A typical *Lisp program has the format 

(defun top-level () 

(initialize-non-cm-variables) 

(*cold-boot -.initial-dimensions *my-own-dimensions*) 
(initialize-cm-variables) 

(main-function)) 

There are many reasonable exceptions to this general pattern. For instance, it 
is possible to define VP sets and permanent pvars before calling * cold-boot. 
However, VP sets defined in this way remain uninstantiated and pvars likewise 
do not actually contain data until * cold-boot has been called. 

Language Notes: 

The *Lisp simulator permits an : initial-dimensions argument containing non- 
power-of-two dimensions, but issues a warning that such code cannot be ex¬ 
ecuted on the CM-2 hardware. 

If the function initialize-character is used to define the code, bits, or font field 
sizes of character pvars, it must be called immediately prior to calling *cold- 
boot, because the *Lisp global variables set by initialize-character are used in 
initializing *Lisp and the Connection Machine system. See Chapter 2, “*Lisp 
Global Variables” for a list of global variables controlling character attributes. 
See also the dictionary entry for initialize-character. 

Usage Note: 

The :safety keyword argument to *cold-boot also determines the safety level 
for Paris operations. If the value supplied for: safety is 0, Paris safety is turned 
off. Any other value for the : safety argument turns Paris safety on. 
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References- 

See also the related Connection Machine initialization operator *warm-boot. 
See also the initialization-list functions add-initialization and delete-initialization. 
See also the character attribute initialization operator initialize-character. 
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compare! ! [Function] 

Performs a parallel magnitude comparison on the supplied pvars. 


Syntax- 

compare!! numeric-pvarl numeric-pvarl 


Arguments- 

numeric-pvarl, numeric-pvar2 

Non-complex numeric pvars to be compared. 


Returned Value- 

compare-pvar Temporary integer pvar. In each active processor, contains 
either 1, 0, or -1 depending on whether the value of numeric- 
pvarl is greater than, equal to, or less than the value of 
numeric-pvar2. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar having values -1,0, or 1, depending on whether its first 
argument is less than, equal to, or greater than its second argument, respectively. 
The arguments numeric-pvarl and numeric-pvar2 must both be non-complex 
numeric pvars. A pvar of type (pvar (signed-byte 2)) is returned. 


Examples- 

(compare!! pvarl pvar2) <=> (signum!! (-!! pvarl pvar2)) 
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References 
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complex!! [ Function] 

Creates and returns a complex numeric pvar. 


Syntax- 

complex!! realpart-pvar &optional imagpart-pvar 


Arguments- 

realpart-pvar Non-complex numeric pvar. Real part of new complex pvar. 

imagpart-pvar Non-complex numeric pvar. Imaginary part of new complex 
pvar. 

Returned Value- 

complex-pvar Temporary complex pvar. In each active processor, contains a 
complex value with real and imaginary components equal to 
the corresponding values of realpart-pvar and imagpart-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a complex pvar that has, in each processor, the realpart-pvar 
component as its real part and the imagpart-pvar component as its imaginary part. 
Conversion according to the rule of floating-point contagion takes place as neces¬ 
sary. That is, the bit field lengths of the exponent and significand components of 
floating-point numbers in all active processors are guaranteed to be as large as the 
largest representation of either component in any active processor. 

The arguments realpart-pvar and imagpart-pvar must be non-complex numeric 
pvars. If imagpart-pvar is not specified, then an imaginary part pvar of (!! 0) is 
provided. 
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(complex!! (!! 2) (!! 3)) <=> (!! #c(2 3)) 

(complex!! realpart-pvar) 

<=> 

(coerce!! realpart-pvar '(pvar (complex float)) 


Examples 


Notes 


References- 

See also these related complex pvar operators: 
abs!! cis!! 

conjugate!! imagpart!! phase!! 

realpart!! 
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complexp!! [Function] 

Performs a parallel test for complex values on the supplied pvar. 


Syntax- 

complexp!! pvar 


Arguments- 

pvar Pvar expression. Pvar to be tested for complex values. 


Returned Value- 

complexp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where pvar contains a complex value. Contains nil in 
all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This predicate returns t in each processor whose value of pvar is a complex 
number; it returns nil elsewhere. 
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Examples- 

(complexp!! (!! #c(2 3))) <=> t!! 


Notes 


References- 

See also these related pvar data type predicates: 

booleanp!! characterp!! 

floatpl! front-end-p!! integerp!! 

numberp!! string-char-p!! structurep!! 

typep!! 
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*COnd [Macro] 

Evaluates *Lisp forms with the currently selected set bound according to the results of 
a series of boolean tests. 


Syntax 


*cond ( test-pvar-1 
( test-pvar-2 

( test-pvar-n 


body-forms-1 ) 
body-forms-2 ) 

body-forms-n ) 


Arguments- 

test-pvar-n Boolean pvar expression. Selects processors that perform the 

corresponding body-forms. 

body-forms-n *Lisp forms. Evaluated with the currently selected set bound to 
those processors in which test-pvar-n has the value t and all 
previous test-pvar expressions have the value nil. 

Returned Value- 

nil Evaluated for side-effect only. 


Side Effects- 

None other than those of the body-forms. 


Description- 

This form is analogous to the Common Lisp cond operator. Unlike cond, however, 
*cond evaluates all clauses. 

The currently selected set with which each of the clauses is evaluated is determined 
by the test-pvar expressions. The forms in body-forms-n are evaluated with the cur¬ 
rently selected set bound to those processors in which test-pvar-n has the value t 


279 



*cond 


*Lisp Dictionary 


and all previous test-pvar expressions have the value nil. Providing t! S as the final 
test-pvar expression selects all remaining processors. 


Examples- 

When the expressions 

(*defvar result) 

(*let ((mod4 (mod!! (self-address!!) (!! 4)))) 
(*cond 

((=!! mod4 (!! 0)) (*set result (!! 0))) 
((<=!! (!! 1) mod4 (!! 2)) 

(*set result (self-address!!))) 

(t! ! (*set result (!! -1))))) 

are evaluated, result is bound to a pvar such that 

(ppp result :end 10) 

displays the values 

012-1056-109 


Notes 


Language Note: 

Even if there are no selected processors, all consequent forms are evaluated. 
For example, in the expression 


(*cond 

((minusp!! 

((plusp!! 

((zerop!! 

(t!! (when 


(self-address!!)) 
(self-address!!)) 
(self-address!!)) 
(*or t!!) 


(do-negative-actions)) 
(do-positive-actions)) 
(do-zero-actions)) 


(error "This clause cannot be executed")))) 


the call to do-negative-actions is evaluated, even though no processors have a 
negative self address. The do-positive-actions call is evaluated with the cur- 
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rently selected set bound to all processors with a positive send address, and the 
do-zero-actions is evaluated by the single remaining processor with a send 
address of 0. The final t!! clause is also evaluated, even though all processors 
have been selected by the two preceding clauses. 

Note the use, in the final t! ! clause, of the standard *Lisp idiom (*or t! !) to 
determine whether any processors remain active. Since all processors have 
been selected by preceding clauses, (*or t! !) returns nil, preventing the call to 
error from being evaluated. Using an enclosing (when (*or t! !) ...) of this kind 
is a simple method of preventing evaluation of any *cond clause that should 
not be evaluated when no processors are selected. 

Usage Note: 

Forms such as throw, return, return-from, and go may be used to exit an exter¬ 
nal block or looping construct from within a processor selection operator. 
However, doing so will leave the currently selected set in the state it was in at 
the time the non-local exit form is executed. To avoid this, use the *Lisp macro 

with-css-saved. 

See the dictionary entry for with-css-saved for more information. 

Performance Note: 

In the CM-2 implementation of *Lisp, *cond clauses execute serially, in the 
order in which they are supplied. At any given time, therefore, the number of 
processors active within a *cond clause is a subset of the currently selected set 
at the time the *cond form was entered. Providing a large number of clauses to 
*cond (and likewise cond!!) therefore results in potentially low overall use of 
processors. 


References- 

The related macro cond!! returns a value based on the forms that it executes. See 
the dictionary entry for cond!! for more information. 

See also the related operators 
*all *case case!! 

*ecase ecase!! *if if!! 

*unless *when with-css-saved 
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COnd!! [ Function ] 

Returns a pvar obtained by evaluating *Lisp forms with the currently selected set 
bound according to the results of a series of boolean tests. 


Syntax 


cond!! ( test-pvar-1 
( test-pvar-2 


value-forms-1 ) 
value-forms-2 ) 


( test-pvar-n value-forms-n ) 


Arguments- 

test-pvar-n Boolean pvar expression. Selects processors that perform the 

corresponding value-forms. 

value-forms-n *Lisp forms. Evaluated with the currently selected set bound to 
those processors in which test-pvar-n has the value t and all 
previous test-pvar expressions have the value nil. 

Returned Value- 

cond-value-pvar Temporary pvar. In each active processor, contains the value 
returned by value-forms-n if and only if test-pvar-n has the 
value t and all previous test-pvar expressions have the value nil. 


Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

If there are no clauses, cond!! returns nil!!. Otherwise, cond!! is roughly equivalent 
to the following pseudo-code: 

(if!! pvar-1 

(progn al1-the-forms-for-clausel) 

(cond!! (rest clauses)) 

However, if there are no value-forms in a given clause, the test-pvar itself is used as 
the value of the clause, analogous to the Common Lisp cond. 

If any active processor is not assigned a value by one of the clauses, the value of the 
returned pvar in that processor is nil, as if an implicit final clause of (t!! nil !!) were 
evaluated. An explicit final clause of the form 

(t!! (!! default-value)) 

can be used to specify some other “default” processor value. 


Examples- 

The expression 

(ppp (*let ((mod4 (mod!! (self-address!!) (!! 4)))) 

(cond!! 

(( = !! mod4 (!! 0)) (!! 0)) 

((<=!! (!! 1) mod4 (!! 2)) (self-address!!)) 
(t! ! (! ! -1)))) 

:end 8) 

displays the values 
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Notes- 

Compiler Note: 

Because an implicit (t!! nil !!) clause is evaluated to obtain a value for any active 
processor not assigned a value by one of the supplied clauses, the *Lisp com¬ 
piler can occasionally fail to compile an apparently correct cond! ! expression, 
if the clauses return other than pvars of type boolean. For example, given the 
following declarations 

(•proclaim '(type single-float-pvar x y)) 

(*defvar x) 

(*defvar y) 

the function 

(defun does-not-compile () 

;; Note that no final t!! clause is included, so an 
;; implicit (t!! nil!!) clause is provided. 

(*set (the single-float-pvar x) 

(cond!! 

((minusp!! (the single-float-pvar y)) (!! -1.0)) 

((plusp!! (the single-float-pvar y)) (!! 1.0)) 

))) 

does not compile. The *Lisp compiler signals an error because the implicit 
(t! ! nil!!) clause returns boolean values that cannot be stored in a pvar of type 
single-float-pvar. Adding an explicit final clause that returns single-float 
values, as in 

(defun does-compile () 

;; A final t!! clause that returns a single-float 
;; result is included, so this function will be compiled, 
(♦set (the single-float-pvar x) 

(cond!! 

((minusp!! (the single-float-pvar y)) (!! -1.0)) 
((plusp!! (the single-float-pvar y)) (!! 1.0)) 

(t!! (!! 0.0)) 

))) 

allows this function to compile. 
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Performance Note: 

In the CM-2 implementation of *Lisp, cond!! clauses execute serially, in the 
order in which they are supplied. At any given time, therefore, the number of 
processors active within a cond! ! clause is a subset of the currently selected set 
at the time the cond !! form was entered. Providing a large number of clauses to 
cond!! (and likewise *cond) therefore results in potentially low overall use of 
processors. 


References- 

See also *cond, which is a similar macro executed for side effect only. 

See also the related operators 

•all 

•case case!! 

•ecase ecase!! 

•if if!! 

•unless *when 

with-css-saved 
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conjugate!! [Function] 

Calculates in parallel the complex conjugate of the supplied pvar. 


Syntax- 

conjugate!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which the complex conjugate is calcu¬ 
lated. 


Returned Value- 

conjugate-pvar Temporary numeric pvar. Contains in each active processor 
the complex conjugate of the corresponding value of numeric- 
pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

Returns a temporary pvar whose value in each processor is the complex conjugate 
of the corresponding value of numeric-pvar. (The conjugate of a complex number is 
another complex number with the same real component and the negation of the 
imaginary component of the original number.) 

(conjugate!! (!! #c(4 5))) <=> (!! #c(4 -5)) 
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Examples- 

Notes- 

References- 

See also these related complex pvar operators: 

abs!! cis!! complex!! 

imagpart!! phase!! realpart!! 
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copy-seq !! [Function] 

Returns a copy of the supplied sequence pvar. 

Syntax- 

copy-seq !! sequence-pvar 


Arguments- 

sequence-pvar Sequence pvar. Pvar to be copied. Must be a vector pvar. 

Returned Value- 

copy-seq-pvar Temporary sequence pvar. Contains in each active processor a 
copy of the corresponding value of sequence-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a copy of sequence-pvar. 
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Examples- 

(copy-seq!! data-pvar) 


(*defvar seq-pvar (!! #(1 2 3 4))) 

(ppp seq-pvar :end 5) 

#(1 2 3 4) #(1 2 3 4) #(1 2 3 4) #(1 2 3 4) #(1 234) 

(*let ((seq-copy (copy-seq!! seq-pvar))) 

(*setf (pref seq-copy 2) #(4 321)) 

(ppp seq-copy :end 5)) 

#(1 234) #(1 234) #(4 321) #(1 234) #(1 234) 
(ppp seq-pvar tend 5) 

#(1 2 3 4) #(1 2 3 4) #(1 234) #(123 4) #(1 234) 
returns a copy of data-pvar as a temporary pvar on the stack. 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See also these related *Lisp sequence operators: 

*fill length!! 

*nreverse reduce!! reverse!! 

subseq!! 


See also the generalized array mapping functions amap!! and *map. 
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COS!! [Function] 

Takes the cosine of the supplied pvar. 

Syntax- 

cos!! radians-pvar 

Arguments- 

radians-pvar Numeric pvar. Angle, in radians, for which the cosine is calcu¬ 
lated. 

Returned Value- 

cosine-pvar Temporary numeric pvar. In each active processor, contains 

the cosine of the corresponding value of radians-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

The function cos!! returns the cosine of its pvar argument. 


291 




cos!! *Lisp Dictionary 


Examples- 

(cos!! (!! 0)) <=> (!! 1) 


Notes 


References 
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cosh!! 

Takes the hyperbolic cosine of the supplied pvar 

Syntax- 

cosh!! radians-pvar 

Arguments- 

radians-pvar Numeric pvar. Angle, in radians, for which the hyperbolic co¬ 
sine is calculated. 


[Function] 


Returned Value- 

cosh-pvar Temporary numeric pvar. In each active processor, contains 

the hyperbolic cosine of the corresponding value of 
radians-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function cosh !! returns a temporary pvar whose value in each processor is the 
hyperbolic cosine of the value in radians-pvar. 
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Examples- 

(cosh!! (!! 1)) <=> (!! 1.5430806) 


Notes- 

References 
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COUnt!! [Function] 

Performs a parallel count on a sequence pvar, returning in each processor the number 
of sequence elements that match a given item. 


Syntax- 

count!! item-pvar sequence-pvar &key :from-end :test :test-not 

:start :end :key 


Arguments 


item-pvar Pvar expression. Item to match in the corresponding value of 

sequence-pvar. Must be of the same data type as the elements 
of sequence-pvar. 

sequence-pvar Sequence pvar. Contains sequences to be searched. 

:from-end Boolean pvar. Whether to begin search from end of sequence 

in each processor. 

:test Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

:test-not Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a nil result. 

:start Integer pvar. Zero-based index of sequence element at which 

counting starts in each processor. If not specified, counting be¬ 
gins with first element. 

:end Integer pvar. Zero-based index of sequence element at which 

counting ends in each processor. If not specified, counting con¬ 
tinues to end of sequence. 

:key One-argument pvar accessor function. Applied to sequence- 

pvar before counting is performed. 
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Returned Value- 

count-pvar Temporary integer pvar. In each active processor, contains the 

number of elements of sequence-pvar that matched item ac¬ 
cording to the function supplied to :test (or to :test-not ). If the 
sequence pvar contains no elements, (!! 0) is returned. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp count function. 

In each processor, the function count!! searches sequence-pvar for elements that 
match item-pvar. It returns a pvar containing a count of the matching elements 
found in each processor. 

Elements of sequence-pvar are tested against item-pvar with the eql! ! operator un¬ 
less another comparison operator is supplied as either of the :test or :test-not key¬ 
word arguments. The keywords :test and :test-not may not be used together. A 
lambda form that takes two pvar arguments and returns a boolean pvar result may 
be supplied as either the :test and :test-not argument. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of 
sequence-pvar. 


296 















*Lisp Dictionary 


count!! 


Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References 


See also the functions count-if!! and count-if-not!!. They search sequence-pvar 
for elements that either do or do not pass a supplied test and return a count of the 
number of elements found. 


The functions count!!, count-if! !, and count-if-not! ! are similar to the *Lisp func¬ 
tions find!!, find—if !!, and find—if—not! !. Unlike the find functions, however, count 
search continues until sequence-pvar is exhausted. 


These functions are members of a group of similar sequence operators, 
listed below: 

count!! count-if!! count-if-not!! 

find!! find—if!! find—if—not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 


See also the generalized array mapping functions amap!! and "map. 


r 
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COlint-if!! [Function] 

Performs a parallel count on a sequence pvar, returning in each processor the number 
of sequence elements satisfying the supplied test. 

Syntax- 

count-if!! test sequence-pvar &key :from-end :start :end :key 


One-argument pvar predicate. Used to test elements of 
sequence-pvar. 

Sequence pvar. Contains sequences to be searched. 

Boolean pvar. Whether to begin search from end of sequence 
in each processor. 

Integer pvar. Zero-based index of sequence element at which 
counting starts in each processor. If not specified, counting be¬ 
gins with first element. 

Integer pvar. Zero-based index of sequence element at which 
counting ends in each processor. If not specified, counting con¬ 
tinues to end of sequence. 

One-argument pvar accessor function. Applied to 
sequence-pvar before counting is performed. 

Returned Value- 

count-pvar Temporary integer pvar. In each active processor, contains the 

number of elements of sequence-pvar that satisfied test. If the 
sequence pvar contains no elements, (!! 0) is returned. 

Side Effects- 

The returned pvar is allocated on the stack. 


Arguments- 

test 

sequence-pvar 

:from-end 

: start 

:end 

:key 
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Description- 

This function is the parallel equivalent of the Common Lisp count-if function. 

In each processor, the function count-if! ! searches sequence-pvar for elements that 
satisfy the supplied test. It returns a pvar containing a count of the sequence ele¬ 
ments found in each processor. A lambda form that takes a single pvar argument 
and returns a boolean pvar result may be supplied as the test argument. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 

Examples- 

Notes-- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

The functions count!!, count-if!!, and count-if-not!! are similar to the *Lisp func¬ 
tions find!!, find—if !!, and find—if—not! !. Here, however, the search continues until 
sequence-pvar is exhausted. 

These functions are members of a group of similar sequence operators, 
listed below: 

count!! count-if!! count-if-not!! 

find!! find—if!! find—if—not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute—if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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count-if-not!! [Function] 

Performs a parallel count on a sequence pvar, returning in each processor the number 
of sequence elements failing the supplied test. 


Syntax- 

count-if-not!! test sequence-pvar &key :from-end :start :end :key 


Arguments 


test One-argument scalar predicate. Used to test elements of se- 

quence-pvar. 

sequence-pvar Sequence pvar. Contains sequences to be searched. 


:from-end 


: start 


:end 


:key 


Boolean pvar. Whether to begin search from end of sequence 
in each processor. 

Integer pvar. Zero-based index of sequence element at which 
counting starts in each processor. If not specified, counting be¬ 
gins with first element. 

Integer pvar. Zero-based index of sequence element at which 
counting ends in each processor. If not specified, counting con¬ 
tinues to end of sequence. 

One-argument pvar accessor function. Applied to 
sequence-pvar before counting is performed. 


Returned Value- 

count-pvar Temporary integer pvar. In each active processor, contains the 

number of elements of sequence-pvar that failed test. If the se¬ 
quence pvar contains no elements, (!! 0) is returned. 

Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

This function is the parallel equivalent of the Common Lisp count-if-not function. 

In each processor, the function count-if-not!! searches sequence-pvar for ele¬ 
ments that fail the supplied test. It returns a pvar containing a count of the se¬ 
quence elements found in each processor. A lambda form that takes a single pvar 
argument and returns a boolean pvar result may be supplied as the test argument. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 


Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References 


The functions count!!, count-if!!, and count-if-not!! are similar to the *Lisp func¬ 
tions find!!, find—if !!, and find—if—not! !. Here, however, the search continues until 
sequence-pvar is exhausted. 


These functions are members of a group of similar sequence operators, 
listed below: 

count!! count-if!! count-if-not!! 

find!! find—if!! find—if—not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute—if!! substitute-if-not!! 


See also the generalized array mapping functions amap!! and "map. 
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create-geometry [Function] 

Creates and returns a geometry object. 

Syntax- 

create-geometry &key :dimensions :weights :ordering 

:on-chip-bits :off-chip-bits 

Arguments- 

: dimensions Required argument. A list of integers, each of which must be a 

power of 2. Defines the size of each dimension specified by the 
returned geometry object. 

:weights List of integers, one for each dimension. Indicates relative fre¬ 

quency of NEWS communication expected for each dimension. 
Default value assigns equal weight to each dimension. If a 
:weights argument is supplied, neither of the : on-chip-bits 
and :off-chip-bits arguments should be supplied. 

: ordering List of symbols, one for each dimension. Only the symbols 

: news-order and :send-order may be supplied in the list. Con¬ 
trols optimization of address translation for each dimension. 
Default value assigns the symbol: news-order to each dimen¬ 
sion. 

:on-chip-bits, :off-chip-bits 

Lists of integers, one for each dimension. Determine processor 
address translation. These arguments are provided in *Lisp as 
a direct hook into Paris. 


Returned Value-— 

geometry-obj Geometry object, suitable as an argument to *cold-boot, 
def-vp-set, create-vp-set, set-vp-set-geometry, and alloca- 
te-processors-for-vp-set. 
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Side Effects 

None. 


Description- 

The create-geometry function creates and returns a data structure known as a 
geometry object. Geometry objects are used to define the shape of virtual proces¬ 
sor sets. In addition, they permit control over interprocessor communication 
speed within a VP set. This can be particularly useful when it is critical to optimize 
the performance of scanning operations along specific dimensions of a VP set. 

Specifying a dimensions keyword argument is mandatory. The value of the 
dimensions keyword must be a list of integers, each of which must be a power of 2. 
These dimensions specify an n-dimensional hypercube of virtual processors. The 
product of the dimensions must be a power of two multiple of the physical machine 
size. 

If supplied, the value of :weights specifies the relative frequency of NEWS commu¬ 
nication along each dimension. Given the specified weighting, the Connection Ma¬ 
chine allocates virtual processors for optimal performance. 

For example, consider a three-dimensional VP set in which near neighbor commu¬ 
nication is estimated to be twice as frequent in dimension 1 as in either dimension 0 
or 2. In this case, the :weights argument should be the list ’(1 2 1). 

If supplied, the value of ‘.ordering controls optimization of address translation for 
each dimension. For dimensions specified as : news-order, send addresses are 
gray-coded and mapped into NEWS addresses. This ensures that processors with 
neighboring send addresses are actually NEWS neighbors within the machine. For 
dimensions specified as :send-order, no special address translation is done. Pro¬ 
cessors with neighboring geometry positions along these dimensions have neigh¬ 
boring send addresses. 

The :on-chip-bits and :off-chip-bits arguments together specify a pair of bit- 
masks that map send addresses into NEWS addresses, providing maximum control 
over interprocessor communication patterns at the hardware level. These argu¬ 
ments are provided in *Lisp as a direct hook into Paris. 


304 





*Lisp Dictionary 


create-geometry 


Examples- 

The create-geometry function is most often used to specify the geometry of a VP 
set. For example, 

(def-vp-set three-dee nil 
:geometry-definition-form 

(create-geometry :dimensions '(64 128 8) 

:weights '(131) 

:ordering '(:send-order :news-order :send-order))) 

defines a three-dimensional VP set, three-dee. The geometry object returned by 
create-geometry specifies that NEWS communication will take place along di¬ 
mension 1 of three-dee three times as often as along either dimension 0 or 2. Also, 
the geometry object specifies that only dimension 1 of three-dee should be opti¬ 
mized for NEWS addressing. 

The create-geometry function may also be used to instantiate an existing flexible 
VP set, as in 

(def-vp-set flexible-vp-set nil 
:geometry-definition-form nil) 

(allocate-processors-for-vp-set 
flexible-vp-set 
nil 

•.geometry (create-geometry -.dimensions '(32 128 64))) 

which assigns a three-dimensional geometry to the VP set flexible-vp-set. 

Finally, the create-geometry function may be used to specify the geometry of the 
*default-vp-$et*. For example, 

(*cold-boot :initial-geometry-definition 
(create-geometry :dimensions '(32 128))) 

defines a two-dimensional default VP set. 
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Notes- 

The create-geometry function makes it possible to optimize a VP set geometry for 
NEWS communication along certain dimensions and for general send-address 
communication along other dimensions. 

The :weights, -.ordering, :on-chip-bits, and :off-chip-bits arguments default to 
reasonable values if not specified. These arguments affect only the run-time per¬ 
formance of interprocessor communication. They do not affect the data trans¬ 
mitted in any way. 

The majority of *Lisp users will never need to use the : on-chip-bits and 
:off-chip-bits arguments; the weights argument is usually sufficient. 


References- 

See the definitions of *cold-boot, def-vp-set, create-vp-set, let-vp-set, 
set-vp-set-geometry, and allocate-processors-for-vp-set for discussions on 
how to use geometry objects. 

See the Concepts section of the Paris Reference Manual for more information on 
the effect of address orderings. Also in the Paris Reference Manual, see the dictio¬ 
nary entry for CM:create-detailed-geometry. 













*Lisp Dictionary 


create-segment-set!! 


create-segment-set!! [Function] 

Creates and returns a segment set structure pvar that defines a segment set. 


Syntax- 

create-segment-set!! &key :start-bit :end-bit 


Arguments- 

: start-bit Boolean pvar. Specifies processors that start a segment. If not 

supplied, starting processors are determined from :end-bit 
argument. 

: end-bit Boolean pvar. Specifies processors that end a segment. If not 

supplied, starting processors are determined from : start-bit 
argument. 


Returned Value- 

segment-set-obj Segment set pvar, suitable for use as the third argument in a 
call to the segment-set-scan!! operation. 


Side Effects 

None. 


Description- 

This function returns a segment set pvar suitable for use as the third argument in a 
call to the segment-set-scan!! operation. 

The two keyword arguments to create-segment-set!! specify which processors 
are included in the segments of the segment set. These are boolean pvars, one or 
the other but not both of which may be nil!!. 

The: start-bit argument may be a pvar containing the value t in each processor that 
starts a segment and nil in all other processors. Alternatively, to signify that the 
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: end-bit argument is to be used to determine where the segments start,: start-bit 
may be nil!! or simply not supplied. 

Likewise, the: end-bit argument may be a pvar containing the value t in each proc¬ 
essor that ends a segment and nil in all other processors. To signify that the 
: start-bit argument is to be used to determine where the segments end,: end-bit 
may be nil!! or simply not supplied. 

With these arguments, it is possible to specify a segment set from which certain 
processors are entirely excluded. However, if either argument to 
create-segment-set!! is not supplied, completely adjacent segments are defined. 

When constructing pvars to supply as :start-bit or: end-bit arguments, take care to 
properly interleave the starting and ending processors for each segment. It is an 
error to specify overlapping segments. 

From the segment start and end information, a structure pvar is constructed. The 
structure pvar created by a call to create-segment-set!! is defined as follows: 

(*defstruct segment-set 

(start-bits nil :type boolean) 

(end-bits nil :type boolean) 

(processor-not-in-any-segment nil :type boolean) 
(start-address 0 

:type (signed-byte 32) 

:cm-type (pvar (signed-byte 

(1+ *current-send-address-length*)))) 

(end-address 0 

:type (signed-byte 32) 

:cm-type (pvar (signed-byte 

(1+ *current-send-address-length*))))) 

The start-bits and end-bits slot pvars contain the :start—bit and :end-bit argument 
pvars supplied to create-segment-set!!. The processor-not-in-any-segment 
slot pvar is t in each processor excluded from the segments in the set and nil else¬ 
where. 

The send address of every first and last processor in each segment is calculated and 
stored with the segment-set structure in the start-address and end-address slot 
pvars. In each processor that is included in a segment, the start-address slot pvar 
contains the send address of the first processor in the segment and the 
end-address slot pvar contains the send address of the last processor in the seg¬ 
ment. For processors excluded from all segments in the set, the start-address and 
end-address slot pvars each contain -1. 
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Examples 

Notes — 


References- 

See also these related segment set operators: 

segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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create-vp-set [Function] 

Creates and returns a VP set definition object. 


Syntax- 

create-vp-set dimensions &key :geometry 


Arguments- 

dimensions Either nil or a list of integers, each of which is a power of 2. 

Specifies the dimension sizes of the VP set object returned. 

:geometry Either nil or a geometry object as returned by create- 

geometry. Specifies geometry of VP set object returned. 


Returned Value- 

vp-set-obj VP set object. Descriptor object for newly created VP set. 


Side Effects 

None. 


Description- 

This function is used to define a VP set during program execution. It is an error to 
invoke create-vp-set prior to the first * cold-boot. Any VP set allocated using 
create-vp-set will be destroyed with the next * cold-boot. 

The return value of create-vp-set is a front-end VP set structure. 

The dimensions argument must be a list of positive integers or nil. If a list is sup¬ 
plied, each integer in the list must be an integral power of two and the product of all 
the integers in the list must be at least as large as *minimum-size-for-vp-set\ If 
larger than the physical machine size, the product of all dimensions must be a 
power-of-two multiple of the physical machine size. The dimensions argument 
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must be nil if an argument is supplied to the keyword : geometry. If not nil, dimen¬ 
sions logically specifies an n-dimensional array of virtual processors. 

The argument to :geometry must be a geometry object obtained by calling create- 
geometry. If the : geometry argument is provided, it incorporates information 
about the dimensions of the VP set being defined. (See the definition of create-ge- 
ometry for more details.) 


Examples- 

The *Lisp forms 

(setq x (create-vp-set '(512 8 32)) 

(setq y (create-vp-set (append (vp-set-dimensions x) '(22)))) 

create two VP sets. The first, x, is created with a 3-dimensional configuration. The 
second, y, is created with a 5-dimensional configuration, using the function 
vp-set-dimensions to obtain the dimension sizes specified for the x VP set. 

The create-vp-set function is normally used during program execution, not at top 
level. Below is an example of how create-vp-set might be used in a program. 

(defun make-2d-vp-set (linear-vp-set n linear-pvar) 

(let ((new-vp-set (create-vp-set (list n n)))) 

(*with-vp-set new-vp-set 
(*let ((new-pvar (!! 0))) 

(*with-vp-set linear-vp-set 

(*when (<!! (self-address!!) (!! n)) 

(*pset :no-collisions linear-pvar new-pvar 
(cube-from-vp-grid-address!! 

new-vp-set (self-address!!) (self-address!!))) 
(*with-vp-set new-vp-set 

(ppp new-pvar :mode :grid :end '(4 4))))))) 
(deallocate-vp-set new-vp-set))) 


This example uses create-vp-set to create an n x n vp set, new-vp-set. It then 
creates a pvar, new-pvar, within the two-dimensional new-vp-set, and uses *pset 
to store the first n elements of linear-pvar into the main diagonal elements of new- 
pvar. With new-vp-set selected, a function is called to perform an operation on the 
new-pvar, and finally deallocate-vp-set is called to deallocate the new-vp-set. 

Because n is used to determine the dimensions of VP sets, n must be a power of two. 
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An example of how this function might be called is: 

(defparameter vp-set-size 32) 

(def-vp-set ld-vp-set (list vp-set-size)) 

:*defvars ((ld-pvar (self-address!!)))) 

(make-2d-vp-set ld-vp-set vp-set-size ld-pvar) 

0 0 0 0 
0 10 0 
0 0 2 0 
0 0 0 3 


Notes 


References 


See also the following VP set definition and deallocation operators: 

def-vp-set let-vp-set 

deallocate-def-vp-sets deallocate-vp-set 

See also the following geometry definition operator: 

create-geometry 

The following math utilities are useful in defining the size of VP sets: 

next-power-of-two->= power-of-two-p 

See also the following flexible VP set operators: 

allocate-vp-set-processors allocate-processors-for-vp-set 

deallocate-vp-set-processors deallocate-processors-for-vp-set 

set-vp-set-geometry with-processors-allocated-for-vp-set 

These operations are used to select the current VP set: 

set-vp-set *with-vp-set 


See also the following VP set information operations: 

dimension-size dimension-address-length 

describe-vp-set vp-set-deallocated-p 

vp-set-dimensions vp-set-rank 

vp-set-total-size vp-set-vp-ratio 
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cross-product [Function] 

Returns the cross product of two front-end vectors 

Syntax- 

cross-product vectorl vector2 

Arguments- 

vectorl, vector2 Front-end vectors, for which the cross product is returned. 

Returned Value- 

cross-prod-vector Front-end vector. Cross product of vectorl and vector2. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent of cross-product!!. The cross product of 
the two vectors is computed. The result is returned as a vector. 

(cross-product #(1 2 3) #(4 56)) => #(-3 6 -3) 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

V- 

V* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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cross-product!! [Function] 

Performs a parallel cross product operation on the supplied vector pvars. 


Syntax- 

cross-product!! vector-pvarl vector-pvar2 


Arguments- 

vector-pvarl, vector-pvar2 

Vector pvars, for which the cross product is returned. 


Returned Value- 

cross-prod-vector-pvar 

Temporary vector pvar. In each active processor, contains the 
cross product of the corresponding values of vector-pvarl 
and vector-pvar2. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, the cross product of the two vector pvars is computed. The re¬ 
sult is returned as a vector pvar. 

(cross-product!! (!! #(1 2 3)) (!! #(4 5 6))) <=> 

(!! #(-3 6 -3)) 

The arguments vector-pvarl and vector-pvar2 must each be a pvar vector of type 
(pvar (array single-float (3))). That is, the vector stored in each processor of both 
pvar arguments must be of length 3. 
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cross-product!! 


Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a number of vector pvar operators, listed below: 

cross-product!! dot-product!! 

v+M v-!! v*!! 

vabs!! vabs-squared!! vscale!! 

vscale-to-unit-vector!! *vset-components 

sf-cross-product!! sf-v+-constant!! sf-v—constant!! 

sf-v*-constant!! sf-v/-constant!! sf-vabs!! 

sf-vabs-squared!! sf-vector-normal!! sf-vscale-to-unit-vector!! 

dsf-cross-product!! dsf-vector-normal!! 

dsf-vscale-to-unit-vector!! 
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cube-from-grid-address [Function] 

Converts a grid (NEWS) address in the current VP set into a send (cube) address. 


Syntax- 

cube-from-grid-address coordinate &rest coordinates 


Arguments- 

coordinate, coordinates 

A set of integers representing a grid (NEWS) address in the cur¬ 
rent VP set. The number of coordinates supplied must equal the 
rank of the current VP set. 


Returned Value- 

send-address Integer. The send (cube) address corresponding to the set of 
coordinates. 


Side Effects 

None. 


Description- 

This function translates a series of integers specifying the grid (NEWS) address of a 
single processor in the current VP set into a single integer specifying the send 
(cube) address of that processor. 

Each argument specifies a coordinate point along one axis in an / 7 -dimensional 
grid. At least one argument is required and the number of integer values supplied 
must equal the rank of the current machine configuration. 
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Examples- 

For example, assuming a three-dimensional configuration is in effect: 

(cube-from-grid-address 10 20 30) => 1036 

Here, the processor located at coordinates (10,20,30) has a send (cube) address of 
1036. 


Notes- 

Note that the send (cube) address corresponding to a particular grid address is not 
predictable from the grid address values alone. It also depends on the geometry of 
the current VP set, on the number of physical processors attached, and on the sys¬ 
tem software version in use. In particular, the relationship between send and grid 
addresses in the *Lisp simulator is different from that of the actual CM-2 hard¬ 
ware. 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address, cube-from-vp-grid-address, grid-from-cube-address, and grid- 
from-vp-cube-address. 


References 


See also these related send and grid address translation operators: 


cube-from-grid-address!! 

cube-from-vp-grid-address 

grid-from-cube-address 

grid-from-vp-cube-address 

self-address!! 


cube-from-vp-grid-address!! 

grid-from-cube-address!! 

grid-from-vp-cube-address!! 

self-address-grid!! 
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cube-from-grid-address!! [Function] 

Performs a parallel conversion from grid (NEWS) addresses in the current VP set to 
send (cube) addresses . 


Syntax- 

cube-from-grid-address!! coordinate-pvar &rest coordinate-pvars 


Arguments- 

coordinate-pvar, coordinate-pvars 

A series of integer pvars representing, in each processor, a grid 
(NEWS) address in the current VP set. The number of coordina¬ 
te-pvars supplied must equal the rank of the current VP set. 


Returned Value- 

send-address-pvar Temporary integer pvar. In each active processor, contains the 
send (cube) address corresponding to the values of the coordi¬ 
nate-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function translates a series of coordinate-pvars, specifying a grid (NEWS) ad¬ 
dress in each processor in the current VP set, into a single pvar that contains the 
corresponding send (cube) address in each processor. 

This is the parallel equivalent of cube-from-grid-address. 
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Examples- 

For example, assuming a three-dimensional configuration is in effect: 

(cube-from-grid-address!! (!! 10) (!! 20) (!! 30)) 

=> (!! 1036) 

Here, the send (cube) address of the processor located at coordinates (10, 20,30), 
1036, is returned in all active processors. 


Notes- 

Note that the send (cube) address corresponding to a particular grid (NEWS) ad¬ 
dress is not predictable from the grid (NEWS) address values alone. It also depends 
on the geometry of the current VP set, on the number of physical processors at¬ 
tached, and on the system software version in use. 

For example, on the CM hardware, the expression 

(*cold-boot :initial-dimensions '(32 16)) 

(ppp (cube-from-grid-address!! 

(self-address-grid!! (!! 0)) 

(self-address-grid!! (!! 1))) 

:mode :grid :end "(4 4)) 

may display the following: 

0 123 
4567 
8 9 10 11 
12 13 14 15 

On the *Lisp simulator, the same code displays 

0 16 32 48 

1 17 33 49 

2 18 34 50 

3 19 35 51 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address!!, cube-from-vp-grid-address!!, grid-from-cube-address!!, and 
grid-from-vp-cube-address!!. 
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cube-f rom-grid-address!! 


References- 

See also these related send and grid address translation operators: 

cube-f rom-grid-address 

cube-f rom-vp-grid-address cube-f rom-vp-grid-address!! 

grid-from-cube-address grid-from-cube-address!! 

grid-from-vp-cube-address grid-from-vp-cube-address!! 

self-address!! self-address-grid!! 
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cube-from-vp-grid-address [Function] 

Converts a grid (NEWS) address in the specified VP set into a send (cube) address. 


Syntax- 

cube-from-vp-grid-address vp-set coordinate &rest coordinates 


Arguments- 

vp-set VP set object. VP set for which the supplied coordinates are 

converted. Must be both defined and instantiated. 

coordinate, coordinates 

A set of integers representing a grid (NEWS) address in vp-set. 
The number of coordinates supplied must equal the rank of 
vp-set. 


Returned Value- 

send-address Integer. The send (cube) address corresponding to the set of 
coordinates. 


Side Effects 

None. 


Description- 

This function translates a series of integer coordinates that specify the grid (NEWS) 
address of a single processor in vp-set into a single integer specifying the send 
(cube) address of that processor. 
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Examples- 

For example, assuming the VP set my-vp has a three-dimensional geometry, 

(cube-from-vp-grid-address my-vp 10 20 30) => 1036 

Here, the processor located at coordinates (10, 20, 30) in the my-vp VP set has a 
send (cube) address of 1036. This means that the processor at coordinates (10, 
20,30) in my-vp can be accessed directly via the send address 1036, as in 

(pref (self-address!!) 1036) => 1036 

Using this conversion mechanism, it is unnecessary to make my-vp the current VP 
set in order to access processors via grid addresses within my-vp, as in 

(*with-vp-set my-vp 

(pref (self-address!!) (grid 10 20 30))) => 1036 


Notes- 

Note that the send (cube) address corresponding to a particular grid (NEWS) ad¬ 
dress is not predictable from the grid (NEWS) address values alone. It also depends 
on the geometry of the current VP set, on the number of physical processors at¬ 
tached, and on the system software version in use. 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address, cube-from-vp-grid-address, grid-from-cube-address, and grid- 
from-vp-cube-address. 


References 


See also these related send and grid 

cube-from-grid-address 
cube-from-vp-grid-address!! 
grid-from-cube-address 
grid-from-vp-cube-address 
self-address!! 


address translation operators: 
cube-from-grid-address!! 

grid-from-cube-address!! 

grid-from-vp-cube-address!! 

seif-address-grid!! 
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cube-from-vp-grid-address!! 


cube-from-vp-grid-address!! [Function] 

Performs a parallel conversion from grid (NEWS) addresses in the specified VP set into 
send (cube) addresses. 


Syntax- 

cube-from-vp-grid-address!! vp-set coordinate-pvar &rest coordinate-pvars 


Arguments- 

vp-set VP set object. VP set for which the coordinates in the supplied 

coordinate-pvars are converted. Must be both defined and in¬ 
stantiated. 

coordinate-pvar, coordinate-pvars 

A set of integer pvars representing in each processor a grid 
(NEWS) address in vp-set. The number of coordinate-pvars 
supplied must equal the rank of vp-set. 


Returned Value- 

send-address-pvar Temporary integer pvar. In each active processor, contains the 
send (cube) address corresponding to the values of the coordi¬ 
nate-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function converts a series of coordinate-pvars, specifying the grid (NEWS) ad¬ 
dresses of processors in vp-set, into a single pvar that specifies the send (cube) 
addresses of those processors. This is the parallel equivalent of cube-from-vp- 
grid-address. 
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Examples- 

For example, assuming the VP set my-vp has a three-dimensional geometry, 

(cube-from-vp-grid-address!! 

my-vp (!! 10) (!! 20) (!! 30)) => (!! 1036) 

Here, the send (cube) address of the processor located at coordinates (10,20,30) in 
the my-vp VP set, 1036, is returned in all active processors. 


Notes- 

Note that the send (cube) address corresponding to a particular grid (NEWS) ad¬ 
dress is not predictable from the grid (NEWS) address values alone. It also depends 
on the geometry of the current VP set, on the number of physical processors at¬ 
tached, and on the system software version in use. 

For example, on the CM hardware, the expression 

(def-vp-set two-dim '(32 16)) 

(ppp (cube-from-vp-grid-address!! two-dim 
(self-address-grid!! (!! 0)) 

(self-address-grid!! (!! 1))) 

:mode :grid :end '(4 4)) 

may display the following: 

0123 
4567 
8 9 10 11 
12 13 14 15 

On the *Lisp simulator, the same code displays 

0 16 32 48 

1 17 33 49 

2 18 34 50 

3 19 35 51 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address!!, cube-from-vp-grid-address!!, grid-from-cube-address!!, and 
grid-from-vp-cube-address!!. 
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cube-f rom-vp-grid-address!! 


References- 

See also these related send and grid address translation operators: 

cube-f rom-grid-address cube-f rom-grid-address!! 

cube-f rom-vp-grid-address 

grid-from-cube-address grid-from-cube-address!! 

grid-from-vp-cube-address grid-from-vp-cube-address!! 

self-address!! self-address-grid!! 
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* d e al I ocate [Function] 

Deallocates a global pvar. 

Syntax- 

"deallocate pvar 

Arguments- 

pvar Pvar expression. The global pvar to deallocate. Must have been 

allocated by allocate!!. 

Returned Value- 

nil Evaluated for side effect. 

Side Effects- 

Deallocates the global pvar pvar, freeing the heap memory assigned to it on the 
CM. 


Description- 

This function deallocates the supplied global pvar, which must have been allocated 
by allocate!!. 
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Examples- 

(allocate!! global-pvar) 
;code using global-pvar 
(♦deallocate global-pvar) 


Notes- 

It is an error to use a pvar after it has been deallocated. The order in which pvars 
are deallocated does not matter. 

Global pvars and permanent pvars are allocated on the CM heap. In contrast to 
global pvars, which are allocated by allocate!! and deallocated with deallocate*, 
permanent pvars, are allocated by *defvar and must be deallocated by the function 

*deallocate-*defvars. 


References- 

See also the pvar allocation and deallocation operations 


allocate!! 

array!! 


*deallocate-*defvars 

*defvar 


front-end!! 

Met 

Met* 

make-array!! 

typed-vector!! 

vector!! 

!! 




See the *Lisp glossary for definitions of the different kinds of pvars that are allo¬ 
cated on the CM stack and heap. 
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*deallocate-*defvars [Function] 

Deallocates some or all permanent pvars allocated by *defvar. 


Syntax- 

*deallocate-*defvars &rest pvar-names 


Arguments- 

pvar-names A series of symbols naming permanent pvars that have been 
allocated by *defvar, or one of the symbols : prompt, :all, 
:all-noconfirm, or nil. Specifies the pvars to deallocate. 

Returned Value- 

nil Evaluated for side-effect. 


Side Effects- 

Deallocates the permanent pvars specified by pvar-names, freeing the CM heap 
memory they have occupied. 


Description- 

This function deallocates the pvars specified in pvar-names. 

If pvar-names is nil or : prompt, the user is prompted with the name of each pvar 
ever declared with *defvar, and given the option of deallocating the pvar, or of 
skipping it and going on to the next pvar. Skipped pvars are not deallocated. 

lipvar-names is tall, then after the user is prompted for confirmation all pvars allo¬ 
cated with *defvar are deallocated. 

lipvar-names is :all-noconfirm, then all pvars declared with *defvar are deallo¬ 
cated. 
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Examples- 

Here are some sample uses: 


(♦deallocate-*defvars 'foo) 
(♦deallocate-*defvars 'foo 'bar) 
(♦deallocate-*defvars :prompt) 

(♦deallocate-♦defvars) 

(♦deallocate-♦defvars :all) 


;delete foo pvar 

; delete foo and bar pvars 

;get prompted for pvars 
;to delete 

;get prompted for pvars 
;to delete 

;delete all pvars declared 
;with *defvar 


Notes- 

Before deallocating any permanent pvar, be certain that no library functions 
depend on that pvar. 

The two predefined pvars, t!! and nil!!, can never be deallocated. 

Global pvars and permanent pvars are allocated on the CM heap. In contrast to 
global pvars, which are allocated by allocate!! and deallocated with deallocate*, 
permanent pvars, are allocated by * defvar and must be deallocated by the function 

*deallocate-*defvars. 


References- 

See also the pvar allocation and deallocation operations 


allocate!! 

array!! 


‘deallocate 

* defvar 


front-end!! 

•let 

•let* 

make-array!! 

typed-vector!! 

vector!! 


m 

See the *Lisp glossary for definitions of the different kinds of pvars that are allo¬ 
cated on the CM stack and heap. 
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deallocate-def-vp-sets [Function] 

Deallocates some or all permanent VP sets, which were defined using def-vp-set. 

Syntax- 

deallocate-def-vp-sets &rest vp-sets 

Arguments- 

vp-sets VP sets to be deallocated, or the keyword :all. 

Returned Value- 

nil Evaluated for side effect. 

Side Effects- 

Deallocates VP sets specified by vp-sets using deallocate-vp-set. 

Description- 

This function deallocates each of the supplied vp-sets, using deallocate-vp-set. If 
the vp-sets argument is the single keyword: all, all VP sets defined using def-vp-set 
are deallocated. 
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deallocate-def-vp-sets 


Examples- 

(deallocate-def-vp-sets vp-set-1 vp-set2) 
(deallocate-def-vp-sets tall) 


Notes 


References- 

See the *Lisp glossary for definitions of the kinds of VP sets that may be allocated 
and deallocated. 

See also the following VP set definition and deallocation operators: 

def-vp-set create-vp-set 

let-vp-set deallocate-vp-set 
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deallocate-processors-for-vp-set [Function] 
deallocate-vp-set-processors [Function] 

Deinstantiates a flexible VP set, deallocating any associated pvars. 


Syntax- 

deallocate-processors-for-vp-set vp-set &key :ok-if-not-in$tantiated 


Arguments- 

vp-set Flexible VP set. Virtual processor set defined with def-vp-set. 

: ok-if-not-instantiated 

Boolean value. Determines whether error is signalled if vp-set 
does not currently have any processors allocated. 


Returned Value- 

nil Evaluated for side effect. 


Side Effects- 

Deinstantiates VP set, and deallocates CM memory assigned to associated pvars. 
Definitions of permanent pvars are retained, and these pvars are reallocated when 
the VP set is reinstantiated. 


Description- 

Deallocates all processors previously allocated for the specified VP set by a call to 
allocate-processors-for-vp-set. 

The vp-set parameter must be a flexible VP set for which processors have been 
allocated by either allocate-processors-for-vp-set or allocate-vp-set- 
processors. The specified VP set itself is not destroyed and the definitions of any 
associated permanent pvars are retained. However, all other pvars, including glob- 
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al pvars created by allocate!!, are deallocated and destroyed by a call to the 
deallocate-processors-for-vp-$et function. 

The :ok-if-not-instantiated keyword takes a boolean argument and defaults to nil. 
It determines whether or not an error is signaled if the provided VP set is not inst¬ 
antiated at the time of the call. 


Examples- 

This example shows howallocate-processors-for-vp-set, along with its compan¬ 
ion function deallocate-processors-for-vp-set, may be used to instantiate a 
flexible VP set several times with a different geometry at each invocation. 

(def-vp-set disk-data nil 

:*defvars ((disk-data-pvar nil nil (pvar single-float)))) 


(defun process-files (&rest diskfiles) 

(♦cold-boot) 

;;; at this point, disk-data-pvar has no memory allocated 

;;; on the CM 

(dolist (file diskfiles) 

(let ((elements (read-number-of-elements-in file))) 
(allocate-processors-for-vp-set disk-data 
(list (next-power-of-two->= elements))) 

;;; now disk-data-pvar has CM memory allocated 
(let ((array-of-data (read-data-from-disk file))) 
(array-to-pvar array-of-data disk-data-pvar 
:cube-address-end elements) 
(process-data-in-cm disk-data disk-data-pvar)) 
(deallocate-processors-for-vp-set disk-data)))) 


Notes- 

The function deallocate-vp-set-processors is an obsolete alias for the function 
deallocate-processors-for-vp-set, and behaves identically. 
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deallocate-processors-for-vp-set 


References- 

See the *Lisp glossary for a definition of flexible VP set and for definitions of all the 
kinds of VP sets that may be allocated and deallocated. 

See also the following flexible VP set operators: 

allocate-vp-set-processors allocate-processors-for-vp-set 
set-vp-set-geometry with-processors-allocated-for-vp-set 

See also the following VP set definition and deallocation operators: 

def-vp-set create-vp-set let-vp-set 

deallocate-def-vp-sets deallocate-vp-set 
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deallOCate-vp-set [Function] 

Deallocates a permanent or temporary VP set and its associated pvars. 


Syntax- 

deallocate-vp-set vp-set &optional deallocate-geometry-p 


Arguments- 

vp-set VP set object. VP set to be deallocated. 

deallocate-geometry-p 

Scalar boolean value. Determines whether the geometry object 
associated with the VP set is deallocated. 


Returned Value- 

retumed-value Returned value. 


Side Effects 


Description- 

This function deallocates the supplied vp-set regardless of whether it was created 
by a call to def-vp-set or to create-vp-set. All pvars belonging to vp-set are 
deallocated as well. If vp-set was defined by def-vp-set, then the symbol that 
names the VP set is made unbound. 

The optional argument, deallocate-geometry-p, is a boolean value that determines 
whether the geometry object associated with the specified VP set is to be deall¬ 
ocated. The default is t; the assocated geometry object is deallocated by default. 
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Examples- 

Notes- 

Usage Note: The let-vp-set form automatically calls deallocate-vp-set using the 
default argument to deallocate-geometry-p. Do not assign a geometry object that 
should be preserved to a temporary VP set created with let-vp-set. 

References- 

See the *Lisp glossary for definitions of permanent and temporary VP sets. 

See also the following VP set definition and deallocation operators: 

def-vp-set create-vp-set 

let-vp-set deallocate-def-vp-sets 
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*decf [Macro] 

Destructively decrements each value of the supplied pvar. 

Syntax- 

*decf numeric-pvar Soptional value-pvar 

Arguments- 

numeric-pvar Pvar expression. Pvar to be decremented. 

value-pvar Numeric pvar. Amount to subtract from numeric-pvar. De¬ 

faults to (!! 1). 

Returned Value- 

nil Evaluated for side effect. 


Side Effects- 

Destructively decrements each value of pvar by the corresponding value of value- 
pvar. 


Description- 

Destructively decrements each element of numeric-pvar by the corresponding val¬ 
ue of value-pvar. The value-pvar argument defaults to (!! 1). 


343 



*decf 


*Lisp Dictionary 


Examples- 

(*decf count-pvar (!! 3)) 


Notes- 

Usage Note: 

A call to the *decf macro expands as follows: 

(*decf data-pvar (!! 4)) 

==> 

(*setf data-pvar (-!! data-pvar (!! 4))) 

For this reason, the numeric-pvar must be a modifiable pvar, such as a permanent, 
global, or local pvar. It is an error to supply a temporary pvar as the numeric-pvar 
to *decf. 


References- 

See also the related macro *incf. 

The function 1-!! can be used to non-destructively perform a subtraction by 1 on 
its argument pvar. See the dictionary entry on 1-!! for more information. 
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*defsetf [Macro] 

Assigns an update function to be used whenever *setf is called on the specified access 
function. 


Syntax- 

•defsetf accessor-function update-function 


Arguments- 

accessor-function Symbol. The name of a parallel structure accessor function. 

update-function Symbol. The name of an update function to be called whenever 
*setf is called on accessor-function. 

Returned Value- 

update-function Name of update function assigned. 

Side Effects- 

Assigns update-function as function to be called whenever *setf is called on 
accessor-function. 

Description- 

Defines the update-function used for a given accessor-function in a call to *setf. 


345 



*defsetf 


*Lisp Dictionary 


Examples- 

(*defsetf 'get-pvar-value 'modify-pvar-value) 


Notes 


References- 

See also the dictionary entry for the *setf macro. 

The macro *undefsetf may be used to remove the assignment made by ‘defsetf. 
See the definition of *undefsetf for more information. 
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*defstruct [Macro] 

Defines a structure pvar type. 

Syntax- 

* defstruct structure-name 

&optional documentation &rest slot-descriptors 

•defstruct ( structure-name &rest options ) 

&optional documentation &rest slot-descriptors 

Arguments- 

structure-name Symbol. Name of structure type. 

options Series of structure option specifiers, described below, that 

control naming conventions and structure inheritance. Each 
supplied option must be of the form 
(: keyword &rest values ) 

documentation String. Documentation string for structure. 

slot-descriptors At least one slot descriptor of the form 

(slot-name default-init &rest slot-options ) 

The three components of the slot-descriptors argument are described below. 

slot-name Symbol. Name of slot. 

default-init Front-end value. Single default value for all elements of the slot. 

Spread to all processors by the function !! when a parallel 
structure object is created. If the :cm-initial-value or :cm- 
uninitialized-p slot options are specified, then this argument is 
ignored when a parallel structure object is created. 

slot-options Series of slot option keyword/value pairs of the form 

:keyword value 
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Returned Value- 

structure-name Returns name of structure type. 

Side Effects- 

Defines both front-end and parallel structure types, along with constructor, 
accessor, copying, and modification operations for both stucture types. 


Description- 

The macro ‘defstruct defines structure pvar types in *Lisp. A call to *defstruct 
defines both a Common Lisp scalar structure type and a Connection Machine par¬ 
allel structure type. Further, *defstruct defines both scalar and parallel construc¬ 
tor, accessor, and assignment operations for these new data types. This double 
functionality of *defstruct allows structures to be passed back and forth between 
the Connection Machine system and the front-end computer. 

A call to *defstruct does the following: 

■ defines a front-end defstruct type structure-name, with slots correspond¬ 
ing to the slot-descriptors of the *defstruct 

■ defines a new pvar type, (pvar structure-name) ; pvars of this type can con¬ 
tain only elements of type structure-name 

■ defines a parallel constructor function mak e-structure-namell, which 
creates pvars of type (pvar structure-name) 

■ defines pvar accessors of the form structure-name-slot-name'. ! that take a 
pvar argument of type (pvar structure-name) and return a copy of the 
structure slot slot-name in parallel 

■ defines *setf methods for these pvar accessors to permit modification of 
the structure pvar slots 

■ defines a *Lisp predicate, structure-name-p\\ to test whether a pvar is a 
parallel structure of the newly defined type 

■ defines a sequence pvar copying operation copy -structure-name'.'., that 
takes a pvar of type (pvar structure-name) and returns a copy of it 
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■ permits the operations !!, *setf of pref. array-to-pvar, pvar-to-array, 
array-to-pvar-grid, and pvar-to-array-grid to accept a front-end defstruct 
object as the value stored in a structure pvar of the corresponding type 

Keyword options in the options list control slot properties and naming conventions 
that apply to the parallel structure type as a whole. The keywords that may be 
supplied in the options list are described below. 

■ :conc-name Symbol. Used instead of structure-name as the 

prefix of slot accessor functions. If this keyword is supplied with a value of 
nil, or with no value at all, no prefix is attached to slot accessor functions. 

■ :cm-constructor Symbol. Used as the name of the structure pvar 

constructor function instead of the default, mak e-structure-nameV.. 

• :parallel-cm-predicate Symbol. Used as the name of the structure pvar 

predicate instead of the default, structure-name-pU. 

■ include Symbol. Names a structure pvar type previous¬ 

ly defined by * defstruct that is to be included in the definition of the new 
structure pvar type. 

■ :cm-uninitialized-p Boolean value. If t, is equivalent to supplying 

the :cm-uninitialized-p slot option in every slot-options list of the *def- 
struct form. Has no effect if nil. 

In addition, almost all structure option keywords permitted by the Common Lisp 
defstruct operator may be included in the options list. (See Chapter 19, 
“Structures,” in Common Lisp, the Language) The values supplied for these key¬ 
words are passed directly on to defstruct, and therefore have their normal effect. 
The only keywords that are not allowed are :type, :named, and : initial-offset. 

Each slot-descriptor argument describes one slot of the parallel structure type be¬ 
ing defined. The slot-name is used to name the slot in both the parallel structure 
type and the front-end structure type. 

The value of default-init for each slot must be a form that returns a valid front-end 
value conforming to the type of the slot, as specified by the :type slot option. This 
value is distributed to all processors, as if by the function !!. If either of the options 
:cm-uninitialized-p or :cm-initial-value is specified in the slot-options list, then 
the default-init argument for that slot is ignored and can be specified as nil. 
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Keyword options in the slot-options list of each slot control typing and initializa¬ 
tion of that slot. 

One keyword option, :type, must be specified for each slot. 

■ :type Type specifier. Specifies data type of structure 

slot, for both front-end structures and structure pvars. This argument must 
specify a Common Lisp data type that is also valid as a pvar element type. 
Slots may not be specified as either general or mutable. 

All other permissible slot-options keywords are described below. 

■ :cm-type Type specifier. Specifies data type of structure 

pvar slots, allowing extra control of structure pvar data types. Overrides 
data type specified by :type argument, but must be of a compatible data 
type (i.e., a more specific definition of the same basic data type). 

■ :cm-initial-value *Lisp form. Evaluated when structure pvars 

are created to provide default value for this structure slot. If unspecified, 
structure slot is initialized using default-init argument. 

■ :cm-uninitialized-p Boolean value. If t, structure objects are 

created with this slot uninitialized. Has no effect if nil. It is an error to sup¬ 
ply a value for :cm-initial-value if the :cm-uninitialized-p argument is t. It 
is also an error to attempt to access an uninitialized structure slot before a 
value has been stored into it. 

■ : read-only Boolean value. If t, indicates that the slot is not 

to be modified. Has no effect if nil. It is an error to try to modify a slot that 
has been declared as : read-only. 


Examples-- 

An example of a call to *defstruct is 

(*defstruct elephant 

(wrinkles 30000 :type (unsigned-byte 16)) 

(tusks t :type boolean)) 

This expression defines both the front-end structure type elephant and a parallel 
structure type of (pvar elephant). 
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The front-end structure type is automatically defined by a call to defstruct of the 
form 

(defstruct elephant 

(wrinkles 30000 :type (unsigned-byte 16)) 

(tusks t :type boolean)) 

which defines a set of construction, accessor, predicate, and copying functions for 
the front-end structure type. The call to *defstruct also defines a set of parallel 
construction, accessor, predicate, and copying functions, described below. 

A parallel structure construction function called make-elephant!! is defined to 
create pvars of type (pvar elephant). For example, the expression 

(*defvar jumbo!! (make-elephant!! :wrinkles (!! 0))) 

defines a variable jumbo!! that contains a pvar with a wrinkle-free, tuskless 
elephant in each processor. 

Parallel slot accessor functions, elephant-wrinkles!! and elephant-trunk!!, are de¬ 
fined, each of which takes a single argument of type (pvar elephant) and returns a 
copy of the contents of the specified slot as a pvar. For example, 

(elephant-wrinkles!! jumbo!!) <=> (!! 0) 

(elephant-tusks!! jumbo!!) <=> t! ! 

Methods are defined for *setf so that these slots can be modified in parallel. For 
example, the expression 

(*setf (elephant-wrinkles!! jumbo!!) (!! 4000)) 

modifies the value of the wrinkles slot of each elephant structure in jumbo! ! so that 
every elephant is moderately wrinkled. 

Methods are also defined for *setf so that a single value of a structure pvar of type 
(pvar elephant) can be modified. 

(*setf (pref jumbo!! 0) 

(make-elephant :wrinkles 4000 :tusks t)) 
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A parallel structure predicate, elephant-p!!, is defined. This takes a single pvar 
argument and returns t!! if it is of type (pvar elephant). 

(elephant-p!! jumbo!!) => t!! 

Finally, a parallel structure copying function, copy-elephant!!, is defined. It takes 
a pvar of type (pvar elephant), and returns a copy as a temporary pvar. 

(*defvar jumbo-copy!!) 

(*set jumbo-copy!! (copy-elephant!! jumbo!!)) 


Notes- 

Language Note: 

Structure pvar slot accessor functions return a copy of the structure slot. If it is 
necessary to obtain the actual contents of the slot rather than a copy (e.g., to 
pass a slot to a function that modifies the slot’s contents), use the macro alias!! 
in combination with the slot accessor function. However, it is only necessary to 
use the alias!! operator in specific circumstances. See the definition of alias!! 
for more information on where and when it should be used. 

Important: the *setf macro automatically accesses the actual value specified 
by a slot accessor, so it is unnecessary to use alias! ! in combination with *setf. 
For example, the expression 

(*setf (alias!! (elephant-wrinkles!! jumbo!!)) (!! 4000)) 
can be equivalently, and more efficiently, written as 

(*setf (elephant-wrinkles!! jumbo!!) (!! 4000)) 


Usage Note: 

It is an error for any two slots to have the same name. Also, if any slot is given a 
slot-name of p, the p slot accessor structname- p will be shadowed by the 
structname structure pvar predicate structname- p. To get around this, use the 
*defstruct :conc-name option with an argument such as structname-ge\-s\o\. 


352 






*Lisp Dictionary 


defstruct 


References- 

For a more detailed discussion of the ‘defstruct macro and of structure pvars in 
general, along with more examples of the use of ‘defstruct, see Chapter 4, entitled 
“Structure Pvars,” in the *Lisp Reference Manual Supplement Version 5.0. 

The ‘defstruct macro is a parallel version of the Common Lisp defstruct macro. 
For a discussion of defstruct, and of the use of structures in Common Lisp, see 
Chapter 19, “Structures,” in Common Lisp, the Language. 
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*defun [Macro] 

Defines a *Lisp operator that takes pvar arguments and/or returns a pvar value, and 
automatically resets the CM stack upon exiting. 

Syntax- 

*defun fn-name arg-list &optional declarations documentation &body body 

Arguments- 

fn-name 
arg-list 
declarations 
documentation 
body 

Returned Value 

fn-name Symbol. Name of parallel function being defined. 

Side Effects- 

Defines both a macro named fn-name and a function with a symbol name derived 
from fn-name. 


Symbol. Name of function. 

List of arguments. Identical to the arglist parameter of defun. 
Optional type declaration forms. 

Optional documentation strings. 

*Lisp forms. Body of function. 


Description- 

In general, user-defined functions containing *Lisp expressions may be defined 
using the Common Lisp defun operator. However, temporary pvars created during 
execution of some user-defined *Lisp functions can cause *Lisp to run out of stack 
space. The *Lisp operator *defun should be used in place of defun to define such 
functions. 
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The *defun macro is analogous to the Common Lisp defun and can be used in 
place of it in defining a function that accepts pvar arguments or returns a pvar 
result. However, the *def un macro adds extra code to reset the CM stack when the 
function exits, thus deallocating any temporary pvars that have been created 
during execution of the function. For efficiency, the *def un macro should be used 
only to define functions that must reset the CM stack. 

The declarations argument can be any number of *Lisp declaration forms. These 
forms can include, but are not limited to, type declarations for the arguments to the 
function being defined by *defun. The documentation argument may be any num¬ 
ber of documentation strings for the function. 

There are two cases where a user-defined function would have to reset the CM 
stack. One is where the function will be called outside of *Lisp operators, such as 
•set and *when, that automatically reset the *Lisp stack when they exit. Another is 
where the function will be used within a complicated *Lisp expression that causes 
*Lisp to run out of stack space. 

There are four rules to use in determining which *Lisp operators clear the CM 
stack, and therefore where it may be necessary to use *defun: 

■ Operators defined by *defun always reset the CM stack. These operators 
are indicated, both in their Dictionary entries and in the table of contents, 
by the notation [*Defun]. 

■ All of the pvar pretty printing operators (ppp, ppp-css, etc.) reset the 
CM stack. 

■ The following macros reset the CM stack: 


all 

*and 

‘apply 

•cond 

*ca$e 


decf 

•ecase 

*funcall 

*if 

•integer-length 

incf 

"let 

•let* 

•logand 

•logior 

•logxor 

map 

•max 

*min 

•or 

pref 

•pset 

set 

*setf 

*sum 

•unless 

•when 

with-css-saved 


*xor 

■ Functions whose names end in !! do not reset the CM stack. 
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A heuristic to follow in deciding whether or not to use *defun to define a function is 
that a user-defined function that takes pvar arguments and does not return a pvar 
value (such as the log-sum-pvar example below) should be defined using *defun, 
because these functions will most likely be called outside of a form such as * set that 
takes care of resetting the stack. Conversely, a user-defined function that takes 
pvar arguments and does return a pvar value should not be defined with *defun, 
unless its use causes *Lisp to run out of stack space. 

One can declare that a function has been defined by 'defun with the 'proclaim 
operator. This allows the Common Lisp compiler to see that the “function” defined 
by * defun is actually a macro. For example, 

(♦proclaim '(*defun foo)) 

(defun bar (x) (foo x)) 

(*defun foo (x) (*sum x)) 

Without the call to 'proclaim, when bar is compiled the call to foo is treated as a 
function call. When foo is defined with 'defun, it is actually defined as a macro, so 
that the call to foo within bar will not execute properly. Declaring that foo will be 
defined by 'defun prior to the definition of any function that calls foo allows Lisp 
to compile these functions properly. 


Examples- 

A sample call to 'defun is 

(*defun simply-functional (x y z) 

"A quite simple function of three complex arguments." 
"Author: Dent" 

(declare (type single-complex-pvar x y z)) 

(+! ! x y z)) 

An example of a case where 'defun is necessary is the expression 

(let ((total 0)) 

(dotimes (i limit) 

(setq total (log-sum-pvar (random!! (!! i)))))) 
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If the function log-sum-pvar is defined by 

(defun log-sum-pvar (pvar) 

(log (*sum pvar))) 

and if the value of limit is very large, the expression above will run out of stack 
space. The problem is that the expression (random!! (!! i)) creates a temporary 
pvar on the CM stack on each iteration. The function log-sum-pvar does not reset 
the stack when it exits, and neither does any operator surrounding it within the 
dotimes loop. As the loop repeats, new temporary pvars are created on the stack 
until the stack is exhausted. 

A better definition is 

(♦defun log-sum-pvar (pvar) 

(log (*sum pvar))) 

This adds code that resets the CM stack following each invocation of log-sum- 
pvar. If log-sum-pvar is defined in this way, the example will execute normally. 

An example of a case where the use of *def un is not necessary, and is in fact ineffi¬ 
cient, is the expression 

(dotimes (i limit) 

(*set result-pvar (+!! result-pvar (pvalue (!! i))))) 

If the function pvalue is defined using defun, as in 

(defun pvalue (data-pvar) 

(expt!! data-pvar (random!! (!! 10)))) 

the CM stack will not be exhausted even if limit becomes very large. The reason is 
that, like many *Lisp macros, *set automatically resets the stack after its argument 
expressions have been evaluated. If, in the example above, the function pvalue was 
defined with * defun, then the function would waste time needlessly resetting the 
stack each time around the dotimes loop. 
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Another example of a case in which *defun may be necessary is 

(*proclaim '(ftype (function (t t t t) single-float-pvar) 
component!!)) 

(defun component!! (x y z w) 

(declare (type single-float-pvar x y z w)) 

(+!! (*!! x y) (cos!! z) (sqrt!! w))) 

(defun stack-hog (x) 

(*set x 


(+!!(component!! 

(!! 3.0) 

(! ! 

4.0) 

( ! ! 

5.0) 

( ! 

6.0)) 

(component! ! 

(!! 3.0) 

(! ! 

4.0) 

(M 

5.0) 

( ! 

6.0)) 

(component!! 

(!! 3.0) 

(! ! 

4.0) 

( ! ! 

5.0) 

( ! 

6.0)) 

(component!! 

(!! 3.0) 

( ! ! 

4.0) 

( ! ! 

5.0) 

(! 

6.0))))) 


A call to stack-hog results in a large number of temporary pvars being allocated. 
Each call to component!! allocates four temporary pvars, and the body of 
component! ! generates one or more temporary pvars as it executes. None of these 
pvars are reclaimed until the *set form exits. 

By defining component!! with * defun, rather than defun, any temporary pvars 
allocated during the evaluation of each component! ! form are reclaimed when the 
form exits. These include temporary pvars allocated during evaluation of the 
function’s arguments (i.e., the constant expressions (!! 3.0), (!! 4.0), etc., in the 
example above) and also any temporary pvars generated by the execution of the 
body of component!!. 

By reclaiming the stack each time a call to component! ! exits, the amount of stack 
space required in executing stack-hog is significantly reduced. If a user-defined 
function defined with defun is consistently causing an application to run out of 
stack space, then it should be redefined with *defun. 

Important: By redefining a function with * defun, when the function has previously 
been defined by defun, the function is being redefined as a macro. All forms in 
which the function is called must therefore be recompiled. 

An example of a case where it using *defun is not necessary is 

(*defun pvalue (pvar) 

(expt!! pvar (random!! (!! 10)))) 
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If pvalue is defined with * defun in this way, then the expression 
(dotimes (i limit) 

(*set result-pvar (+!! result-pvar (pvalue (!! i))))) 


will execute unnecessarily slowly. The *set macro automatically resets the stack 
when it exits, but because the pvalue function was defined with ‘defun, it will 
perform an extra, redundant stack reset operation each time around the loop. Re¬ 
defining pvalue with defun will improve performance: 

(defun pvalue (pvar) 

(expt!! pvar (random!! (!! 10)))) 


Notes- 

Implementation Note: 

A call to *defun performs two definitions. It defines both a macro named fn- 
name and a function with a symbol name derived from fit-name. The macro 
expands into a call to the function, with enclosing code that records the original 
state of the stack and ensures that the stack is reset when the function exits. 

Usage Notes: 

To undefine functions created with ‘defun, use the *Lisp operator un*defun. 

To apply ‘defun functions to lists of arguments, use the *Lisp operators ‘apply 
and *funcall. It is an error to use the Common Lisp operators apply and f uncall 
for these purposes. 

The *Lisp tracing operations for *defun functions are ‘trace and ‘untrace. It 
is an error to use the Common Lisp operators trace and untrace to trace a 
function defined with ‘defun. 
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Compiler Note: 

The declarations argument(s) to *defun will not be seen unless the code-walker 
portion of the *Lisp compiler is active. If the code-walker is inactive, these dec¬ 
larations will be seen only if they are enclosed within the * locally operator, as in 

(*defun no-code-walker-function (arg-pvar) 

(♦locally 

(declare (type single-float-pvar arg-pvar)) 

• . . )) 


References 
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*defvar [Macro] 

Allocates a new permanent pvar. 

Syntax- 

•defvar pvar-name &optional initial-value-pvar documentation-string vp-set 

Arguments- 

pvar-name Symbol. Bound to newly allocated pvar. 

initial-value-pvar Pvar expression. If supplied, used to initialize the values of the 
returned pvar. 

documentation-string 

Optional documentation string. 

vp-set VP set object. VP set to which the new pvar will belong. 

Defaults to the value of *default-vp-set*. 


Returned Value- 

pvar-name Returns pvar-name, the symbol to which the new pvar has 

been bound. 


Side Effects- 

Allocates a permanent pvar named pvar-name and binds it to the symbol pvar- 
name. 


Description- 

This creates a new pvar that is permanently allocated. The pvar-name argument is 
a symbol that is bound globally to the allocated pvar. The optional argument 
initial-value-pvar may be any previously allocated pvar or pvar expression. The 
•defvar macro creates a new pvar, initializes it to the contents of initial-value-pvar, 
and binds pvar-name to that new pvar using setq. If no initial-value-pvar argument 
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is given, the allocated pvar is uninitialized. During a * cold-boot operation, un¬ 
less the :undefine-all argument to * cold-boot has been specified as t, all pvars allo¬ 
cated by *defvar are reallocated and the supplied initial-value-pvar expression is 
reevaluated to reinitialize the pvars. 

The optional argument vp-set defines the VP set to which the newly created pvar 
belongs. It defaults to the value of *default-vp-set*. 

The *defvar operator is intended to be used only at top level. It is an error to call 
*defvar from within a user-defined function, as in 

(defun wrong-use-of-*defvar (x) 

(*defvar pvar (!! x)) 

(*defvar pvar-squared (!! (* x x)))) 

The *Lisp operator allocate!! should be used instead to dynamically allocate glob¬ 
al pvars from within a user-defined function. See the definition of allocate!! for 
more information. 


Examples- 

The *defvar macro may be used to create a pvar with a specific initial value, as in 

(*defvar pi!! (!! 3.14159265)) 

or with a value that is the result of a calculation, as in 
(defparameter upper-bound 65536) 

(*defvar limit-pvar (-!! (!! upper-bound) (self-address!!))) 

The *defvar macro may also be used to create a pvar with no initial value, into 
which a value will later be stored by a call to an operator such as *set: 

(*defvar scratch-pvar) 

(*set scratch-pvar (/!! (1+!! (self-address!!)))) 

Note that it is an error to access the contents of a pvar defined in this way until an 
operator such as *set has been used to store a value into the pvar. 

Array pvars and structure pvars may be created by a call to *defvar. However, 
when allocating either of these pvar types using *defvar, it is advisable to declare 
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the type of pvar with * proclaim. Undeclared pvars into which any other type of 
data has been stored cannot be used to hold arrays or structures. For example, 

(♦defvar x) 

(♦set x (!! 3)) 

(♦set x (!! #(1 23))) ;;; This operation is not allowed 

The * defvar macro can be used to create an array pvar in two ways: by directly 
creating the array pvar on the CM with a function such as make-array!!, as in 

(♦proclaim '(type (pvar (array character (3 4 5))) fum)) 
(♦defvar fum (make-array!! '(345) 

•.element-type '(pvar string-char) 
•.initial-element #\L)) 

(ppp (aref!! fum (!! 1) (!! 2) (!! 0)) :end 10) 

#\L #\L #\L #\L #\L #\L #\L #\L #\L #\L 

or by simply using the!! operator to copy a front-end array into all processors, as in 

(♦proclaim '(type (pvar (array (unsigned-byte 8))) fee)) 
(♦defvar fee (!! #(1 2 3))) 

(ppp fee :end 3) 

#(1 2 3) #(1 2 3) #(1 2 3) 

Likewise, structure pvars can be defined by * defvar in two ways: by use of the 
parallel constructor function defined by *defstruct, for instance 

(♦defstruct elephant 

(wrinkles 30000 :type (unsigned-byte 16)) 

(tusks t :type boolean)) 

(♦proclaim '(type (pvar elephant) jumbo!!)) 

(♦defvar jumbo!! (make-elephant!! :wrinkles (!! 300) 

:tusks t!!)) 

(♦proclaim '(type (pvar elephant) jumbo-copy!!)) 

(♦defvar jumbo-copy!! jumbo!!) 
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or by using !! to copy a front-end structure of a type defined by *def struct to all 
processors, as in 

(*defvar white-elephant-pvar 

(!! (make-elephant :wrinkles 0 :tusks nil))) 

The vp-set argument can be used to specify the VP set to which the newly created 
pvar belongs. For example, 

(def-vp-set ptbarnum '(128 128)) 

(*defvar ptbarnum-jumbo (!! 4.0) "Weight in tons" ptbarnum) 

defines a VP set named ptbarnum, and a permanent pvar associated with 
ptbarnum named ptbarnum-jumbo. 

The def-vp-set operator provides a way to lexically associate the definitions of 
permanent pvars with the definition of the VP set to which they belong. See the 
definition of def-vp-set for more information. 


Notes-- 

Language Note: 

Both permanent pvars and global pvars are allocated on the CM heap. Perma¬ 
nent pvars are allocated by * defvar and must be deallocated by the function 
*deallocate-*defvars. In contrast, global pvars are allocated by allocate!! and 
must be deallocated with ‘deallocate. 

Style Note: 

It is a good idea not to provide an initial-value-pvar argument to * defvar that 
is complex or dependant on global variables for its value. In these cases, reeval¬ 
uation of the initialization form when the pvar is reallocated by *cold-boot 
may cause an error. 
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For example, the code fragment 

(♦cold-boot :initial-dimensions '(128 128)) 

(setq image-or-nil 

(make-image-array :dimensions '(128 128))) 

(♦defvar image!! 

(array-to-pvar-grid image-or-nil nil 

:grid-end '(128 128))) 

(setq image-or-nil nil) 

(♦cold-boot) ;;; Error signalled in redefinition 

signals an error on the second invocation of * cold-boot because *Lisp tries to 
reallocate image!! using the variable image-or-nil, which has been set to nil. 

A better way to define pvars of this type is to use * defvar to declare the pvar, 
without an initial-value-pvar argument. The *set operator can then be used 
within an initialization routine to specify the value of the pvar, as in the 
following example: 

(♦defvar data-pvar) 

(defun initialize-pvars () 

(♦set data-pvar 

(complicated-operation-returning-data-pvar))) 


References- 

See also the pvar 

allocate!! 

"deallocate 
front-end!! 
make-array!! 

See also the *Lisp predicate allocated-pvar-p. 

See the *Lisp glossary for definitions of the different kinds of pvars that are allo¬ 
cated on the CM stack and heap. 

See Chapter 4, “*Lisp Types and Declaration,” for more information about pvar 
types, type coercion, and undeclared pvars. 


allocation and deallocation operations 

array!! 

*deallocate-*defvars 

"let "let* 

typed-vector!! vector!! 
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def-vp-set [Macro] 

Defines a permanent VP set object, possibly with associated pvars. 


Syntax- 

def-vp-set v p-set-name vp-set-dimensions 

&key :geometry-definition-form :*defvars 


Arguments- 

vp-set-name Symbol. Name of VP set to which VP set object is bound. 

vp-set-dimensions List of integers or nil. Defines dimensions of VP set. 

:geometry-definition-form 

Geometry object or nil. Defines geometry of VP set. 

: *defvars List of pvar specifiers. Defines pvars created with *defvar that 

are associated with the new VP set. 


Returned Value- 

vp-set-name Symbol. Name of newly defined VP set. 

Side Effects- 

Creates a VP set and binds it to the symbol vp-set-name. Defines all pvars speci¬ 
fied by the :*defvars keyword argument by using *defvar. 


Description- 

The def-vp-set macro defines a permanent VP set named vp-set-name and should 
be used only at top level. Unless the user explicitly specifies that they should be 
deallocated, permanent VP sets and the pvars associated with them are automati¬ 
cally reallocated during a *cold-boot operation. The def-vp-set macro does not 
alter the value of *current-vp-set*. Use the set-vp-set or *with-vp-set operators 
to change the current VP set. 
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The def-vp-set macro returns the symbol vp-set-name, after binding it to a VP set 
object with the specified vp-set-dimensions and associated :*defvars. 

The vp-set-dimensions argument must be a quoted list of positive integers, a form 
that evaluates to a list of positive integers, or nil. If an argument is supplied to the 
keyword :geometry-definition-form, the vp-set-dimensions argument must be nil. 
If not nil, vp-set-dimensions specifies an ^-dimensional array of virtual processors, 
where n is the length of the list of integers supplied. 

Each dimension must be a power of two. The product of all dimensions must be 
equal to either the physical machine size or a power-of-two multiple of the physi¬ 
cal machine size. The total size specified by vp-set-dimensions must be at least as 
large as *minimum-size-for-vp-set*. 

The argument to :geometry-definition-form must be a form which, when evalu¬ 
ated, returns a geometry object. Examples of appropriate forms are: a call to 
create-geometry, a symbol bound to the result of a call to create-geometry, and a 
user-defined form that evaluates to a geometry object. See the definition of 
create-geometry for a description of geometry objects. 

If either vp-set-dimensions or a : geometry-definition-form is supplied, the VP set 
vp-set-name is created as a fixed-size VP set; its geometry is fixed and does not 
change. The returned VP set is initialized and allocated at *cold-boot time. If 
either vp-set-dimensions or a : geometry-definition-form is supplied and a 
’’cold-boot has already been executed, the VP set vp-set-name is initialized and 
allocated immediately. 

If both vp-set-dimensions and the :geometry-definition-form argument are nil, 
then the returned VP set is defined as a flexible VP set. This type of VP set has no 
specific geometry until it has been instantiated by calling the function 
allocate-processors-for-vp-set or with-processors-allocated-for-vp-set. This 
may be done any time after a call has been made to * cold-boot. 

The keyword :*defvars takes a list of lists, each of which specifies a permanent 
pvar that is associated with the VP set vp-set-name. Each sublist must be of the 
form 

( symbol &optional initial-value-form documentation pvar-type ) 

Here, symbol is bound to a pvar with initial value initial-value-form, documenta¬ 
tion documentation, and type pvar-type. 
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For each such sublist, if pvar-type is not nil, a form with the following construction 
is evaluated. 

'(♦proclaim "(type , pvar-type , symbol )) 

Whether or not pvar-type is nil, the following form is evaluated. 

'(♦defvar , symbol , initial-value-form . documentation vp-set ) 

where vp-set is the symbol vp-set-name given as the first argument to def-vp-set. 

The :*defvars keyword provides the ability to textually associate pvars with their 
VP sets. Note that pvars thus specified are allocated and initialized only when the 
VP set set-name is instantiated. Such pvars are reallocated and reinitialized by 

*cold-boot. 


Examples- 

This expression creates a three-dimensional VP set named fred with dimensions 
1024 by 32 by 128. 

(def-vp-set fred '(1024 32 128)) 

This expression creates a two-dimensional VP set named george with a VP ratio of 
32, i.e., thirty-two virtual processors for each physical processor attached. 

(def-vp-set george (list *minimum-size-for-vp-set* 32)) 

The expression 

(def-vp-set anne '(65536) 

:*defvars((x (!! 1) nil (field-pvar 2)) 

(y (self-address!!)))) 

creates a one-dimensional VP set named anne, and defines two permanent pvars 
associated with anne as if by the following forms: 

(def-vp-set anne '(65536)) 

(♦proclaim '(type (field-pvar 2) x)) 

(♦defvar x (!! 1) nil anne) 

(♦defvar y (self-address!!) nil anne) 
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If the arguments vp-set-dimensions and :geometry-definition-form are both nil, 
then a VP set with no initial geometry, known as a flexible VP set , is defined. Flexible 
VP sets must be instantiated before use, by either of the instantiation operators 
allocate-processors-for-vp-set or with-processors-allocated-for-vp-set. For 
example, the pair of expressions 

(def-vp-set gumby nil) 

(allocate-processors-for-vp-set gumby '(128 64 32)) 

defines a flexible VP set named gumby, and instantiates gumby as a three-dimen¬ 
sional VP set. The expression 

(deallocate-processors-for-vp-set gumby) 

deinstantiates gumby, so that it may be instantiated with a different number of 
processors. The expression 

(with-processors-allocated-for-vp-set gumby 
:dimensions '(128 64 32) 

(user-defined-function)) 

performs the same instantiation and deinstantiation automatically, temporarily 
instantiating gumby during the execution of the user-defined-function. 


Notes- 

Because the newly created VP set object is simply bound as the value of the symbol 
vp-set-name, it is a good idea to choose a vp-set-name that will not be used as the 
name of a global variable. For example, if the expressions 

(def-vp-set data-set '(512 512)) 


and 


(*defvar data-set (random!! (self-address!!))) 

are evaluated in order, the permanent pvar created by *defvar will replace the VP 
set created by def-vp-set as the value of the symbol data-set. 
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References- 

See the *Lisp glossary for definitions of permanent, temporary, fixed-size, and 
flexible VP sets. 

See also the following VP set definition and deallocation operators: 

create-vp-set let-vp-set 

deallocate-def-vp-sets deallocate-vp-set 

See also the following geometry definition operator: 

create-geometry 

The following math utilities are useful in defining the size of VP sets: 
next-power-of-two->= power-of-two-p 

See also the following flexible VP set operators: 

allocate-vp-set-processors allocate-processors-for-vp-set 

deallocate-vp-set-processors deallocate-processors-for-vp-set 

set-vp-set-geometry with-processors-allocated-for-vp-set 

These operations are used to select the current VP set: 
set-vp-set *with-vp-set 

See also the following VP set information operations: 

dimension-size dimension-address-length 

describe-vp-set vp-set-deallocated-p 

vp-set-dimensions vp-set-rank 

vp-set-total-size vp-set-vp-ratio 
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delete-initialization [Function] 

Removes *Lisp code placed on initialization lists by add-initialization. 

Syntax- 

delete-initialization name-of-form init-list-name 

Arguments- 

name-of-form Character string. Name of initialization form to remove. 

init-list-name Symbol or list of symbols. Initialization list(s) from which the 

specified initialization form is removed. 

Returned Value- 

nil Executed for side effect. 


Side Effects- 

The named initialization form is removed from the initialization list or lists speci¬ 
fied by init-list-name. 


Description- 

The function delete-initialization removes a named initialization from one or more 
of the following *Lisp initialization lists: 

■ * before-*cold-boot-initializations* 

*Lisp code evaluated immediately prior to any call to * cold-boot. 

■ *after-*cold-boot-initializations* 

*Lisp code evaluated immediately after to any call to *cold-boot. 

■ *before-*warm-boot-initializations* 

*Lisp code evaluated immediately prior to any call to *warm-boot. 
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■ *after-*warm-boot-initializations* 

*Lisp code evaluated immediately after to any call to ‘warm-boot. 

The arguments are specified in the same manner as the first and third arguments 
for add-initialization. 


Examples- 

The function delete-initialization is the recommended way to remove initializa¬ 
tions from the above lists. For example, the expression 

(add-initialization "Recompute Important Pvars" 

'(recompute-important-pvars *number-of-processors-limit*) 

"*after-*cold-boot-initializations*) 

adds an initialization form named “Recompute Important Pvars” to the list 
*after-*cold-boot-initializations*. Evaluating the expression 

(delete-initialization "Recompute Important Pvars" 

'*after-*warm-boot-initializations*) 

will remove the initialization form. 


Notes 


References- 

See also the related operation add-initialization. 

See also the following Connection Machine initialization operators: 

‘cold-boot ‘warm-boot 

See also the character attribute initialization operator initialize-character. 
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deposit-byte!! [Function] 

Performs a parallel byte deposit operation on the supplied pvars. 


Syntax- 

deposit-byte!! into-pvar position-pvar size-pvar byte-pvar 


Arguments — 

into-pvar 

position-pvar 

size-pvar 

byte-pvar 


Integer pvar. Integer into which byte is deposited. 

Integer pvar. Bit position, zero-based, at which value of byte- 
pvar is deposited. 

Integer pvar. Bit size of byte to deposit. 

Integer pvar. Byte to deposit into into-pvar. 


Returned Value- 

newbyte-pvar Temporary integer pvar. In each active processor, contains a 
copy of into-pvar with size-pvar bits beginning at position-pvar 
replaced by low-order bits of byte-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The deposit-byte!! function returns a pvar whose contents are a copy of into-pvar 
with the low-order size-pvar bits of byte-pvar inserted into the bits starting at 
location position-pvar. 

When the into-pvar is positive, zeros are appended as high order bits of byte-pvar as 
needed. When the into-pvar is negative, ones are appended as high order bits of 
byte-pvar as needed. 
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Examples- 

The returned value may have more bits than into-pvar if the inserted field extends 
beyond the most significant bit of into-pvar. For example, 

(deposit-byte!! (!! #B11) (!! 1) (!! 2) (!! #B10)) 

returns 

(!! 5) <=> (!! #B101) 


Notes- 

Usage note: 

This function is especially fast when both position-pvar and size-pvar are con¬ 
stants, as in (!! positive-integer). 

References- 

See also these related byte manipulation operators: 

byte!! byte-position!! byte-size!! 

deposit-field!! dpb!! 

Idb!! Idb—test!! load-byte!! 

mask-field!! 
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deposit-field I! [Function] 

Performs a parallel bit field copy operation on the supplied pvars. 


Syntax- 

deposit-field!! into-pvar bytespec-pvar integer-pvar 


Arguments- 

into-pvar Integer pvar. Integer into which bit field is copied. 

bytespec-pvar Byte specifier pvar, as returned from byte!!. Determines posi¬ 
tion and size of byte in into-pvar which is replaced. 

integer-pvar Integer pvar. Integer from which bit field is copied. 

Returned Value- 

newbyte-pvar Temporary integer pvar. In each active processor, contains a 
copy of into-pvar with size-pvar bits beginning at position-pvar 
replaced by the corresponding bits of integer-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function deposit-field!! is the parallel equivalent of the Common Lisp func¬ 
tion deposit-field. The newbyte-pvar result contains, for each processor, a copy of 
the value of into-pvar with the byte specified by bytespec-pvar replaced by the cor¬ 
responding bits of of integer-pvar. The result therefore agrees with integer-pvar in 
the byte specified, and with the original value of newbyte-pvar everywhere else. 
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Examples- 

(deposit-field newbyte-pvar (byte!! size-pvar position-pvar) 

integer-pvar) 

<=> 

(dpb!! (ldb!! (byte!! size-pvar position-pvar) newbyte-pvar) 
(byte!! size-pvar position-pvar) integer-pvar) 


Notes 


References- 

See also these related byte manipulation operators: 

byte!! byte-position!! byte-size!! 

deposit-byte!! dpb!! 

ldb!! ldb—test!! load-byte!! 

mask-field!! 
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describe-pvar [Function] 

Displays information about a pvar. 

Syntax- 

describe-pvar pvar &optional stream 

Arguments 

pvar 
stream 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

Prints formatted description of pvar to stream. 

Description- 

This function prints out information about pvar in a neat format. The printed in¬ 
formation includes memory location, field-id, length, type, VP set of the pvar. 


Pvar expression. Pvar to describe. 

Stream object. Defaults to *standard-output\ 
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Examples 


(describe-pvar (!! 2)) 

=> 

Pvar Name: nil 
Location: 4 
Field Id: 65536 
Length: 2 
Type: :field 

Vp Set Name: *default-vp-set* 
Vp Dimensions: (32 16) 
Constant value: 2 

nil 


Notes 


References 


See also the following general pvar information operators: 


allocated-pvar-p 

pvar-length 

pvar-name 

pvar-type 


pvar-exponent-length 

pvar-location pvar-mantissa-length 

pvarp pvar-plist 

pvar-vp-set 
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describe-vp-set [Function] 

Displays information about a VP set. 


Syntax- 

describe-vp-set vp-set &key :*defvars :verbose 


Arguments- 

vp-set VP set object. VP set to be described. 

: ‘defvars Boolean value. Determines whether pvars associated with the 

specified VP set are described. Defaults to t. 

:verbose Boolean value. Determines whether to display detailed infor¬ 

mation about the VP set. Defaults to nil. 

Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Prints formatted description of vp-set to the ‘standard-output* stream. If 
:*defvars argument is t, displays information about each pvar associated with 
vp-set. 


Description- 

This function prints information about vp-set. The information displayed by 
describe-vp-set is derived from the front-end VP set structure created when 
vp-set was defined. 

The argument vp-set must be a temporary or permanent VP set that has been de¬ 
fined. If vp-set has not been allocated, describe-vp-set will show most slot values 
as nil. 


383 











*Lisp Dictionary 


describe-vp-set 


The keyword argument to -.verbose must be a boolean. It defaults to nil. If the 
default is used, only the most generally useful information is printed when 
describe-vp-set is invoked. If -.verbose is t, additional information, such as the 
length of the grid address for each dimension, is printed. 


Examples- 

A sample call to describe-vp-set is shown below. 

(describe-vp-set *current-vp-set*) 
vp set name: *default-vp-set* 
geometry allocation form: nil 
dimensions: (32 32) 
geometry-id: 1 
nesting-level: 1 

*defvars belonging to *default-vp-set* 

name: a-foo, initial-value-form: (*lisp-i:make-foo!!), 

type: (pvar (structure foo)) 

name: cube-temp, initial-value-form: (!! 0), 

type: (pvar (unsigned-byte *current-send-address-length*)) 

In the example above, *current-vp-set* is examined and discovered to be 
*default-vp-set*, a two-dimensional VP set with two associated pvars, a-foo and 
cube-temp. The geometry-id is a unique number identifying the geometry of this 
VP set. The nesting-level is the number of nested *with-vp-set forms currently in 
effect for this VP set. 

(describe-vp-set *default-vp-set* -.verbose t) 
vp set name: *default-vp-set* 
geometry allocation form: nil 
dimensions: (32 32) 
geometry-id: 1 
nesting-level: 1 
paris vp id: 1 
geometry rank: 2 
grid-address-lengths: (5 5) 

*defvars belonging to *default-vp-set* 
name: foo, initial-value-form: (!! 2), 
type: nil 

name: cube-temp, initial-value-form: (!! 0), 

type: (pvar (unsigned-byte *current-send-address-length*)) 
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Here, *default-vp-set* is described in more depth by supplying a :verbose value 
of t. The grid-address-lengths list is the value to which *current-grid-address- 
lengths* is bound when this VP set is the currently selected VP set. 


Notes 


References 


See also the following VP set information operations: 


dimension-size 

vp-set-deallocated-p 

vp-set-dimensions 

vp-set-total-size 


dimension-address-length 

vp-set-rank 

vp-set-vp-ratio 
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digit-char!! [Function] 

Performs a parallel conversion from integer digits to characters. 


Syntax 


digit-chari! digit-pvar &optional radix-pvar font-pvar 


Arguments- 

digit-pvar Integer pvar. Numeric value to construct as a character. 

radix-pvar Integer pvar. Radix for which to construct character. Defaults 

to (!! 10). 

font-pvar Integer pvar. Font attribute for newly constructed character. 

Defaults to (!! 0). 


Returned Value- 

char-pvar Temporary character pvar. In each active processor, contains a 

character in the font specified by font-pvar which is the digit 
representation of digit-pvar in the radix specified by 
radix-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function attempts to construct a character pvar containing, in each processor, 
a character of font font-pvar representing the value of digit-pvar in radix 
radix-pvar. In each processor where this is possible, the resulting character is re¬ 
turned. In each processor where this is not possible, nil is returned. 

All arguments must be non-negative integer pvars. 
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The function digit-char!! will never return nil in a processor where the value of 
font-pvar is 0, that of radix-pvar is between 2 and 36 inclusive, and that of digit-pvar 
is less than radix-pvar. 

Characters returned by digit-char!! are always in upper case. 

Examples- 

(digit-char!! (!! 14) (!! 16) ) => (!! #\E) 

Notes- 

References- 

See also the related character/integer pvar conversion operators: 
char-code!! char-int!! code-char!! 

digit-char!! int-char!! 
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digit-char-p!! [Function] 

Performs a parallel test for digit characters on the supplied pvar. 


Syntax- 

digit-char-p!! character-pvar &optional radix-pvar 


Arguments- 

character-pvar Character pvar. Pvar to be tested for digit characters. 

radix-pvar Integer pvar. Determines radix of digit characters that are ac¬ 

cepted as valid. 

Returned Value- 

digit-charp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is a 
valid digit character in the radix radix-pvar. Contains nil in all 
other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function tests character-pvar for digits of radix radix-pvar. 

In each processor containing a character-pvar element that is a digit of the speci¬ 
fied radix, digit-char-p! ! returns a non-negative integer indicating the numeric val¬ 
ue of the digit. In those processors where the elements of character-pvar are not 
digits of the specified radix, digit-char-p!! returns nil. 

Notice that digit character pvars are always also graphic character pvars. 
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The argument character-pvar must be a character pvar, a string-char pvar, or a 
general pvar containing only character or string-char elements. 

The argument radix-pvar must be a positive integer pvar and defaults to (!! 10). 

Examples- 

(digit-char-p!! (!! #\3)) <=> t!! 


Notes 


References 


390 



*Lisp Dictionary 


dimension-address-length 


dimension-address-length [Function] 

Returns the number of bits necessary to represent a NEWS address coordinate for the 
specified dimension in the current VP set. 

Syntax- 

dimension-address-length dimension 

Arguments- 

dimension Integer. Zero-based number of dimension for which address 

length is returned. 

Returned Value- 

bit-length Integer. Number of bits needed to represent a NEWS address 

coordinate for dimension in the current VP set. 

Side Effects- 

None. 

Description- 

This function returns the number of bits necessary to represent a grid address co¬ 
ordinate for the specified dimension. This is simply the element of the list *cur- 
rent-grid-address-lengths* corresponding to the specified dimension. 

The argument dimension must be between 0 and one less than the rank of the cur¬ 
rent VP set. 
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Examples- 

If the value of *current-cm-configuration* is (32 16), then 
(dimension-address-length 0) => 5 


Notes 


References- 

See also the following VP set information operations: 

dimension-size 

describe-vp-set vp-set-deallocated-p 

vp-set-dimensions vp-set-rank 

vp-set-total-size vp-set-vp-ratio 
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dimension-size [Function] 

Returns the size of the specified dimension of the current VP set. 

Syntax- 

dimension-size dimension 


Arguments- 

dimension Integer. Zero-based number of dimension for which the size is 

returned. 

Returned Value- 

dimension-size Integer. Size of specified dimension in current VP set. 

Side Effects- 

None. 

Description- 

This function returns the size of the specified dimension of the current VP set. 

The dimension argument can be any non-negative integer less than the rank of the 
current machine configuration. 
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Examples- 

If the value of *current-cm-configuration* is (32 16), then 
(dimension-size 0) => 32 


Notes 


References- 

See also the following VP set information operations: 

dimension-address-iength 

describe-vp-set vp-set-deallocated-p 

vp-set-dimensions vp-set-rank 

vp-set-total-size vp-set-vp-ratio 
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do-for-selected-processors [Macro] 

Iteratively binds a symbol to the send address of each active processor while executing 
the body of the form. 


Syntax- 

do-for-selected-processors ( symbol) &body body 


Arguments- 

symbol Symbol. Bound to the send address of each active processor. 

body *Lisp forms. Evaluated for each active processor. 


Returned Value- 

nil Normally returns nil, unless a non-local exit operator such as 

return is used within the body. 


Side Effects- 

None other than those produced by the forms in body. 


Description- 

This form evaluates body as many times as there are active processors in the 
currently selected set. On each iteration, symbol bound to the send address of a 
different active processor. 
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Examples- 

Using do-for-selected-processors, the function list-of-active-processors could 
be written as 

(defun my-list-of-active-processors () 

(let ((result nil)) 

(do-for-selected-processors (proc) 

(push proc result)) 

(nreverse result))) 


Notes- 

As with the Common Lisp dotimes, the return function may be used to exit the 
do-for-selected-processors form immediately, returning a value. Normally, 
do-for-selected-processors returns nil. 


References- 

See also the related operation list-of-active-processors. 
See also the related processor selection operators 


*all 


*if 

if!! 

•case 

case!! 

*cond 

cond!! 

•ecase 

ecase!! 

•unless 

•when 

with-css- 

-saved 
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dot-product [Function] 

Returns the dot product of two front-end vectors. 

Syntax- 

dot-product vectorl vector2 

Arguments- 

vectorl, vector2 Front-end vectors for which the dot product is returned. 

Returned Value- 

dot-prod-vector Front-end vector. Dot product of vectorl and vector2. 

Side Effects- 

None. 

Description- 

This is the front-end equivalent of dot-product!!. 
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v 


Examples -- 

(dot-product #(1.0 2,0 3.0) #(4.0 5,0 6.0)) => 32.0 


Notes- 

For those not familiar with dot products, the dot product of two vectors 
( xi, x 2 , x 3 , ...x n ) and ( y h y 2 , y 3 , ...y n ) 
is (xi * yi) + (x 2 * y 2 ) + (x 3 * y 3 ) + ... + (x n * y n ) 

The dot-product operation returns the dot product of vectorl and vector2. 


References 


This function is one of 

dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


number of front-end vector 

cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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dot-product!! [Function] 

Performs a parallel dot product operation on the supplied vector pvars. 


Syntax- 

dot-product!! vector-pvarl vector-pvar2 


Arguments- 

vector-pvarl, vector-pvar2 

Vector pvars, for which the dot product is returned. Both 
vector pvars must have the same number of elements. 


Returned Value- 

dot-prod-pvar Temporary pvar. In each active processor, contains the dot 
product of the corresponding values of vector-pvarl and vec- 
tor-pvar2. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a scalar pvar of the proper type and size. In each processor, 
the inner product of the two vectors is returned. 
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The following forms are equivalent: 

(dot-product!! cl-pvar c2-pvar) 

<=> 

(reduce!! #' + ! ! (amap!! #'*!! cl-pvar c2-pvar)) 

<=> 

(♦let ((result (!! 0))) 

(dotimes (j (♦array-total-size (cl-pvar))) 

(♦incf result (♦!! (aref!! cl-pvar (!! j)) 

(aref!! c2-pvar (!! j))))) 

result)) 


Examples- 

(dot-product!! (!! #(1.0 2.0 3.0)) 

(!! #(4.0 5.0 6.0))) 

<=> 

(!! 32.0) 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabsl! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

$f-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

$f-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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dpb!! [Function] 

Performs a parallel byte deposit operation on the supplied pvars. 


Syntax- 

dpb!! into-pvar bytespec-pvar byte-pvar 


Arguments — 

into-pvar 

bytespec-pvar 

byte-pvar 


Integer pvar. Integer into which byte is deposited. 

Byte specifier pvar, as returned by byte!!. Determines position 
and size of the byte that is replaced in into-pvar. 

Integer pvar. Byte to deposit. 


Returned Value- 

newbyte-pvar Temporary integer pvar. In each active processor, contains a 
copy of into-pvar with the byte specified by bytespec-pvar re¬ 
placed by the value of byte-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function dpb. 

The function dpb! ! returns an integer pvar that is a copy of into-pvar with the byte 
specified by bytespec-pvar replaced by the corresponding byte from byte-pvar. 
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The following forms are equivalent: 

(deposit-byte!! integer-pvar pos-pvar size-pvar newbyte-pvar) 
<=> 

(dpb!! 

newbyte-pvar (byte!! size-pvar position-pvar) integer-pvar) 


Examples 

Notes- 


References- 

See also these related byte manipulation operators: 

byte!! byte-position!! byte-size!! 

deposit-byte!! deposit-field!! 

Idb!! Idb—test!! load-byte!! 

mask-field!! 
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dsf-cross-product!! [*Defun] 

Calculates in parallel the cross product of two single-float vector pvars, and stores the 
result in a supplied pvar. 


Syntax- 

dsf-cross-product!! vdest vector-pvarl vector-pvar2 


Arguments- 

vdest Single-float vector pvar. Destination for result. 

vector-pvarl, vector-pvar2 

Single-float vector pvars. Pvars for which cross product is com¬ 
puted. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

The vdest argument is destructively modified to contain the result. In each active 
processor, vdest contains the cross product of the corresponding values of vector- 
pvarl and vector-pvar2. 


Description- 

This function calculates the cross product of two single-float vector pvars, and 
stores the result in a supplied pvar. 

The arguments vector-pvarl and vector-pvar2 must each be a pvar vector of type 
(pvar (array single-float (3))). That is, the vector stored in each processor of both 
pvar arguments must be of length 3. 

The cross product of the two vector pvars is computed and stored in vdest, which 
must also be a vector pvar of type (pvar (array single-float (3))). 
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Examples 


Notes- 

Usage note: 

For those familiar with the mathematical notation for cross products, the ac¬ 
tion of dsf-cross-product!! may be loosely described as 

vector-pvarl x vector-pvar2 -> vdest 


that is, after calling dsf-cross-product!!, each element of vdest is equal to the 
cross-products of the corresponding elements of vector-pvarl and vector- 
pvar2. 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+1! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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dsf-vector-normal!! [* Defun] 

Calculates in parallel the normalized cross product of two single-float vector pvars, 
and stores the result in a supplied pvar. 


Syntax- 

dsf-vector-normal!! vilest vector-pvarl vector-pvar2 


Arguments- 

vdest Single-float vector pvar. Destination for result. 

vector-pvarl, vector-pvar2 

Single-float vector pvars. Pvars for which normalized cross 
product is computed. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

The vdest argument is destructively modified to contain the normalized cross prod¬ 
uct of vector-pvarl and vector-pvar2. 


Description- 

This function calculates in parallel the normalized cross product of two single-float 
vector pvars, and stores the result in a supplied pvar. The following forms are 
equivalent: 

(dsf-vector-normal!! vdest vector-pvarl vector-pvar2) 

<=> 

(*set vdest 

(vscale-to-unit-vector!! 

(sf-cross-product!! vector-pvarl vector-pvar2)) 
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The arguments vector-pvarl and vector-pvar2 must each be a pvar vector of type 
(pvar (array single-float (3))). That is, the vector stored in each processor of both 
pvar arguments must be of length 3. 

The vector normal of the two pvars is calculated and stored in the supplied vdest 
pvar, which must be a vector pvar of element type (pvar single-float). 


Examples 


Notes- 

Usage note: 

The orientation of the normal vector produced in each processor depends on 
the order of the vector-pvar arguments. Specifically, 

(dsf-vector-normal vdestl vector-pvarl vector-pvar2) 
(dsf-vector-normal vdest2 vector-pvar2 vector-pvarl) 

vdestl <=> (sf-v*-constant vdest2 (!! -1)) 
that is, vdestl is the vector negative of vdest2. 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vscale-to-unit-vector!! 

vabs-squared!! 

*vset-components 

vscale!! 

sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v* -constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

dsf-cross-product!! 

sf-vector-normal!! 

dsf-vector-normal!! 

sf-vscale-to-unit-vector!! 


dsf-vscale-to-unit-vector!! 
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dsf-vscale-to-unit-vector!! 


dsf-vscale-to-unit-vector!! [*Defun] 

Calculates In parallel the result of scaling a single-float vector pvar to unit length, and 
stores the result in a specified pvar. 

Syntax- 

dsf-vscale-to-unit-vector!! vdest vector-pvar 

Arguments- 

vdest 

vector-pvar 

Returned Value 

nil Evaluated for side effect only. 


Single-float vector pvar. Destination for result. 
Single-float vector pvar. Vector pvar to be scaled. 


Side Effects- 

The vdest argument is destructively modified to contain the result. In each active 
processor, vdest contains the result of scaling the value of vector-pvar to a unit- 
length vector. 

Description- 

This function is equivalent to the following operation: 

(dsf-vscale!! vdest vector-pvar (/!! (sf-vabs!! vector-pvar))) 

The vdest argument is destructively modified to contain the result, and must be a 
vector pvar of element type (pvar single-float). 
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Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References 


This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

v+!! 

vabsl! 

vscale-to-unit-vector!! 


dot-product!! 

v-!! 

vabs-squared!! 

*vset-components 


v*!! 

vscale!! 


sf-cross-product!! 
sf-v*-constant!! 
sf-vabs-sq uared!! 


sf-v+-constant!! sf-v—constant!! 

sf-v/-constant!! sf-vabs!! 

sf-vector-normal!! sf-vscale-to-unit-vector!! 


dsf-cross-product!! dsf-vector-normal!! 

dsf-vscale-to-unit-vector!! 
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* ecase [Macro] 

Evaluates *Lisp forms with the currently selected set bound according to the value of a 

pvar expression. Signals an error if any processor is not selected by at least one clause. 

Syntax- 

* ecase value-expression 

(key-expression-1 &rest body-forms-1) 

( key-expression-2 &rest body-forms-2 ) 

( key-expression-n &rest body-forms-n ) 

Arguments- 

value-expression Pvar expression. Value to compare against key-expression-n in 
each clause. 

key-expression Scalar expression. Evaluated, compared with value-expression. 

Selects processors in which to perform the corresponding 
body-forms. 

body-forms *Lisp forms. Evaluated with the currently selected set bound to 

those processors in which value-expression is eql to key- 
expression. 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

None aside from those of the individual body-forms. 
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Description- 

This is a parallel version of the Common Lisp ecase operation. Its useage is simi¬ 
lar to that of *cond. 


Examples- 

For example, when 

(*defvar result (!! 1)) 

(*ecase (mod!! (self-address!!) (!! 4)) 

(0 (*set result (!! 0))) 

((1 2) (*set result (self-address!!))) 

(3 (*set result (!! -1)))) 

is evaluated, result is bound to a pvar with the values 0, 1, 2, -1, 0, 5, 6, -1, etc. 


Notes- 

Usage Note: 

Forms such as throw, return, return-from, and go may be used to exit an exter¬ 
nal block or looping construct from within a processor selection operator. 
However, doing so will leave the currently selected set in the state it was in at 
the time the non-local exit form is executed. To avoid this, use the *Lisp macro 

with-css-saved. 

See the dictionary entry for with-css-saved for more information. 

Performance Note: 

In the CM-2 implementation of *Lisp, * ecase clauses execute serially, in the 
order in which they are supplied. At any given time, therefore, the number of 
processors active within a * ecase clause is a subset of the currently selected set 
at the time the *ecase form was entered. Providing a large number of clauses to 
*ecase (and likewise ecase!!) therefore results in potentially low overall 
processor utilization. 
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ecase 


References- 

See also the related operators 


*all 


•case 

case!! 

*cond 

cond!! 

ecase!! 


*if 

if!! 

•unless 

•when 


with-css-saved 
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ecase!! [Macro] 

Returns a pvar obtained by evaluating *Lisp forms with the currently selected set 
bound according to the value of a pvar expression. Signals an error if any processor is 
not selected by at least one clause. 


Syntax- 

ecase 1! value-expression 

( key-expression-1 &rest body-forms-1) 
(key-expression-2 &rest body-forms-2 ) 

(key-expression-n &rest body-forms-n ) 


Arguments- 

value-expression Pvar expression. Value to compare against each key-expression 
in each clause. 

key-expression Scalar expression. Evaluated, compared with value-expression. 

Selects processors in which to perform the corresponding 
body-forms. 

value-forms *Lisp forms. Evaluated with the currently selected set bound to 

those processors in which value-expression is eql to key- 
expression. 

Returned Value- 

ecase-value-pvar Temporary pvar. In each active processor, contains the value 
returned by value-forms-n if and only if value-expression is eql 
to key-expression-n. 


Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

This is a parallel version of the Common Lisp ecase operation. Its useage is simi¬ 
lar to that of *cond. 

If two clauses contain the same key, the returned pvar contains the values returned 
by the body forms in the first of the clauses. 


Examples- 

For example, the pvar returned by 

(ecase!! (mod!! (self-address!!) (!! 4)) 
(0 (!! 0 )) 

((1 2) (self-address!!)) 

(3 (! ! -1))) 

contains the values 0, 1, 2, -1, 0, 5, 6, -1, etc. 


Notes- 

Performance Note: 

In the CM-2 implementation of *Lisp, ecase!! clauses execute serially, in the 
order in which they are supplied. At any given time, therefore, the number of 
processors active within a ecase!! clause is a subset of the currently selected 
set at the time the ecase!! form was entered. Providing a large number of 
clauses to ecase!! (and likewise *ecase) therefore results in potentially low 
overall processor utilization. 


References- 

See also the related operators 
*all ‘case case!! 

*cond cond!! ‘ecase 

‘if if!! 

‘unless ‘when 
with-css-saved 
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enumerate!! [Function] 

Returns a pvar with a unique integer in each active processor. 


Syntax- 

enumerate!! 


Arguments- 

Takes no arguments. 

Returned Value- 

enumerated-pvar Temporary pvar. Contains a unique integer value in each active 
processor. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar that contains, in each active processor, a unique num¬ 
ber from 0 up to one less than the number of selected processors. The numbers are 
ordered, with 0 placed in the processor with the smallest send address, 1 placed in 
the processor with the next smallest send address, and so on. 

(enumerate!!) <=> (1-!! (scan!! (!! 1) '+!!)) 
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Examples- 

The enumerate!! function enumerates active processors. For example, the 
expression 

(ppp (if!! (oddp!! (self-address!!)) 

(enumerate!!) 

(!! 99)) 

:end 10) 

displays the following values 

99 0 99 1 99 2 99 3 99 4 

Note that only the odd processors (those selected by the (oddp!! (self-address!!)) 
test form) are enumerated. 

The enumerate! ! function is often used to pack values in active processors into the 
first n processors, where n is the number of active processors. For example 

(*defvar pvar-to-be-packed (random!! (!! 10))) 

(PPP pvar-to-be-packed tend 10) 

8319221431 

(*defvar packed-pvar (!! 0)) 

(*when (evenp!! (self-address!!)) 

(*pset :no-collisions pvar-to-be-packed packed-pvar 
(enumerate!!))) 

(ppp packed-pvar tend 5) 

8 12 13 

The values in the active (even) processors are packed into the first n !2 processors. 
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Notes- 

If all processors in the CM are selected, enumerate!! is equivalent to the function 
self-address!!. However, in this case, calling self-address!! itself is much more ef¬ 
ficient. 


References- 

See also the related functions 

rank!! self!! 

self-address!! self-address-grid!! sort!! 
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eq!! [ Function] 

Performs a parallel comparison of the supplied pvars for identical values. 


Syntax- 

eq!! pvarl pvarl 


Arguments- 

pvarl, pvar2 Simple pvars. Compared in parallel for identical values. 


Returned Value- 

eq-pvar Temporary boolean pvar. In each active processor, contains 

the value t if pvarl and pvar2 contain identical values. Contains 
nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function eq. It performs a par¬ 
allel comparison of the supplied pvars for identical numeric and character values. 
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Examples- 

(eq!! (!! #\c) (!! #\c)) <=> t! ! 


Notes- 

Language Note: 

There is no fundamental difference between the operations performed by the 
functions eql!! and eq!! in *Lisp. This differs from Common Lisp, where eql 
and eq are defined such that eql performs a less restrictive test than eq. Both 
eq!! and eql!! are included in *Lisp for readability, and programmers should 
use the test that most clearly indicates the type of comparison being per¬ 
formed. 


References 
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eql!! [Function] 

Performs a parallel comparison of the supplied pvars for identical values. 


Syntax- 

eql!! pvarl pvar2 


Arguments- 

pvarl, pvar2 Simple pvars. Compared in parallel for identical values. 


Returned Value- 

eql-pvar Temporary boolean pvar. In each active processor, contains 

the value t if pvarl and pvar2 contain identical values. Contains 
nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function eql. It performs a par¬ 
allel comparison of the supplied pvars for identical values. Numbers of the same 
type and value are considered identical by eql!!, as are character objects that 
represent the same character. 
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Examples- 

(eqlM (!! #\c) (!! #\c)) <=> t! ! 


Notes- 

Language Note: 

There is no fundamental difference between the operations performed by the 
functions eql!! and eq!! in *Lisp. This differs from Common Lisp, where eql 
and eq are defined such that eql performs a less restrictive test than eq. Both 
eq!! and eql!! are included in *Lisp for readability, and programmers should 
use the test that most clearly indicates the type of comparison being per¬ 
formed. 


References 
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equalp!! [Function] 

Performs a parallel comparison of the supplied pvars for equality. 


Syntax- 

equalp!! pvarl pvar2 


Arguments- 

pvarl, pvar2 Pvars. Compared in parallel for equality. 


Returned Value- 

equalp-pvar Temporary boolean pvar. In each active processor, contains 
the value t if the values of pvarl and pvar2 are equal. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is equivalent to eql!! if pvarl and pvar2 are boolean pvars. It is 
equivalent to char-equal!! if they are character pvars. If pvarl and pvar2 are nu¬ 
meric pvars, it is equivalent to =!!. If the parameters are structures or arrays, 
equalp! ! returns the logical AND of calling itself on the slot pvars or element pvars, 
respectively, of the structures or arrays. 
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Examples - 

Notes- 

References 
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evenp!! [Function] 

Performs a parallel test for even numeric values on the supplied pvar. 


Syntax- 

evenp!! integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar to be tested for even values. 


Returned Value- 

evenp-pvar Temporary boolean pvar. Contains the value t in each active 

processor where the corresponding value of integer-pvar is 
even. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The pvar returned by this predicate contains t in each processor where the value of 
the argument integer-pvar is even, and nil in all others. It is an error if any compo¬ 
nent of integer-pvar is not an integer. 
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Examples- 

(evenp!! (!! 2)) <=> t!! 

Notes- 

References- 
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every!! [Function] 

Tests in parallel whether the supplied pvar predicate is true for every set of elements 
having the same indices in the supplied sequence pvars. 


Syntax- 

every!! predicate sequence-pvar &rest sequence-pvars 


Arguments- 

predicate Boolean pvar predicate. Used to test elements of sequences in 

the sequence-pvar arguments. Must take as many arguments as 
the number of sequence-pvar arguments supplied. 

sequence-pvar, sequence-pvars 

Sequence pvars. Pvars containing, in each processor, 
sequences to be tested by predicate. 


Returned Value- 

evety-pvar Temporary boolean pvar. Contains the value t in each active 

processor in which every set of elements having the same in¬ 
dices in the sequences of the sequence-pvars satisfies the predi¬ 
cate. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The every!! function returns a boolean pvar indicating in each processor whether 
the supplied predicate is true for every set of elements with the same indices in the 
sequences of the supplied sequence-pvars. 
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In each processor, the predicate is first applied to the index 0 elements of the 
sequences in the sequence-pvars, then to the index 1 elements, and so on. The nth 
time predicate is called, it is applied to the nth element of each of the sequences. If 
predicate returns nil in any processor, that processor is temporarily removed from 
the currently selected set for the remainder of the operation. The operation contin¬ 
ues until the shortest of the sequence-pvars is exhausted, or until no processors 
remain selected. 

The pvar returned by every!! contains t in each processor where predicate returns 
the value t for every set of sequence elements. If predicate returns nil for any set of 
sequence elements in a given processor, every!! returns nil in that processor. 


Examples 


(every!! 'equalp!! (!! #(1 23)) (!! #(1 23))) <=> t!! 

(every!! '<!! (!! #(1 2 3)) (!! #(2 3 0))) <=> nil!! 
(every!! '<!! (!! #(1 2 3)) (!! 2 3 4 1))) <=> t!! 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See the related functions notany!!, notevery!!, and some!!. 
See also the general mapping function amap!!. 
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exp!! [Function] 

Computes in parallel the value of e raised to the power specified by the supplied pvar. 


Syntax-— 

exp!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Power to which e is raised. 


Returned Value-- 

exp-pvar Temporary numeric pvar. Contains in each active processor 

the value of e raised to the power specified by the correspond¬ 
ing value of numeric-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function computes and returns the value of e raised to the power numeric- 
pvar in each processor, where e is the base of the natural logarithms. Both complex 
and non-complex arguments are accepted. 
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Examples 


(exp!! 

(! 

D) <=> 

(! ! 

2.7182817) 

(exp!! 

(! 

3)) 

<=> 

(!! 20.085535) 

(exp!! 

(! 

! #C(2 2))) 

<=> 

(!! #c(-3.0749323 6.7188506)) 


Notes- 

References 
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expt!! [Function] 

Computes in parallel the result of raising the first supplied pvar to the power specified 
by the second. 


Syntax- 

expt!! base-pvar power-pvar 


Arguments- 

base-pvar Numeric pvar. Value to be raised to a power. 

power-pvar Numeric pvar. Power to which base-pvar is raised. 


Returned Value- 

expt-pvar Temporary numeric pvar. In each active processor, contains 

the result of raising the value of base-pvar to the power speci¬ 
fied by the corresponding value of power-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function computes and returns a pvar containing base-pvar raised to the 
power power-pvar in each processor. 


Examples 


(expt!! (!! 2) (!! 3)) <=> (!! 8) 
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Notes- 

The function expt!! will never return a complex pvar as its result unless base-pvar is 
complex, or is coerced into complex form by use of the functions complex!! or 
coerce!!, as shown below. 

(expt!! (coerce!! (!! -1) '(pvar (complex single-float))) 

(!! 2 )) 

<=> 

(expt!! (complex!! (!! -1)) (!! 2)) 

<=> 

(!! #c(1.0 0.0)) 

It is an error if the argument base-pvar is a negative floating-point pvar and the 
argument power-pvar is a floating-point pvar. It is also an error if the argument 
base-pvar is an integer pvar and argument power-pvar contains negative integers. 


References 
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fceiling!! [Function] 

Performs a parallel floating-point ceiling operation on the supplied pvar(s). 


Syntax- 

fceiling!! numeric-pvar &optional divisor-numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Value for which the floating-point 
ceiling is calculated. 

divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di¬ 
vided by divisor-numeric-pvar before the ceiling is taken. 


Returned Value- 

fceiling-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the floating-point ceiling of numeric-pvar , divided by divi¬ 
sor-numeric-pvar if supplied. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function fceiling. The 
value returned by fceiling!! is the same as that returned by ceiling!!, except that the 
result in each processor is always a floating-point number rather than an integer. 
The following forms are equivalent: 

(fceiling!! data-pvar) <=> (float!! (ceiling!! data-pvar)) 
The argument pvars may contain either integer or floating-point values. 
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Examples 


Notes 


References- 

See also these related rounding operations: 

ceiling!! floor!! round!! truncate!! 

See also these related floating-point operations: 

ffloor!! float!! 

float-sign!! fround!! ftruncate!! 

scale-float!! 
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fflOOr!! [IFunction] 

Performs a parallel floating-point floor operation on the supplied pvar(s). 


Syntax- 

ffloor!! numeric-pvar &optional divisor-numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Value for which the floating-point 
floor is calculated. 

divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di¬ 
vided by divisor-numeric-pvar before the floor is taken. 


Returned Value- 

ffloor-pvar Temporary floating-point pvar. In each active processor, con¬ 

tains the floating-point floor of numeric-pvar, divided by divi¬ 
sor-numeric-pvar if supplied. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function ffloor. The 
value returned by ffloor!! is the same as that returned by floor!!, except that the 
result in each processor is always a floating-point number rather than an integer. 
The following forms are equivalent: 

(ffloor!! data-pvar) <=> (float!! (floor!! data-pvar)) 

The argument pvars may contain either integer or floating-point values. 
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Examples 


Notes 


References- 

See also these related rounding operations: 

ceiling!! floor!! round!! truncate!! 

See also these related floating-point operations: 
fceiling!! float!! 

float-sign!! fround!! ftruncate!! 

scale-float!! 
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*fill {* Defun] 

Destructively modifies some or all elements in each sequence of the supplied sequence 
pvar to contain the specified item. 

Syntax- 

•fill sequence-pvar item &key :start :end 


Arguments- 

sequence-pvar 

item 

: start 

tend 


Sequence pvar. Pvar containing sequences to be modified. 

Scalar value. Value to be stored in sequences. 

Integer pvar. Zero-based index of sequence element at which 
to start fill operation. Default is (!! 0). 

Integer pvar. Zero-based index of sequence element at which 
to end fill operation. Default is (length!! sequence-pvar). 


Returned Value- 

sequence-pvar Returns the modified sequence pvar. 


Side Effects 

None. 


Description- 

This function destructively modifies sequence-pvar by filling each sequence ele¬ 
ment with item. 

The argument sequence-pvar must be a vector pvar. The argument item must be a 
pvar of the same type as the elements of sequence-pvar. The : start and :end argu¬ 
ments define a subsequence of elements to be modified in each sequence. 
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Examples- 

Notes-- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

See also these related *Lisp sequence operators: 

copy-seq!! length!! 

•nreverse reduce!! reverse!! 

subseq!! 

See also the generalized array mapping functions amap!! and *map. 
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find!! [Function] 

Performs a parallel search on a sequence pvar, returning in each processor the first 
sequence element matching the supplied item. 


Syntax- 

find!! item-pvar sequence-pvar 

&key :from-end :test :test-not 

:start :end :key :retum-va!ue-if-not-found 


Arguments- 

item-pvar Pvar expression. Item to match in the corresponding value of 

sequence-pvar. Must be of the same data type as the elements 
of sequence-pvar. 

sequence-pvar Sequence pvar. Contains sequences to be searched. 

:from-end Boolean pvar. Whether to begin search from end of sequence 

in all processors. Defaults to nil. 

:test Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

:test-not Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a nil result. 

: start Integer pvar. Index, zero-based, of sequence element at which 

search starts in each processor. If not specified, search begins 
with first element. 

:end Integer pvar. Index, zero-based, of sequence element at which 

search ends in each processor. If not specified, search contin¬ 
ues to end of sequence. 

:key One-argument pvar accessor function. Applied to each ele¬ 

ment in sequence-pvar before test is performed. 

: return-value-if-not-f ound 

Pvar expression. Value to return in processors where sequence- 
pvar does not contain the item in item-pvar. Default is nil!!. 
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Returned Value- 

find-pvar Temporary pvar, of same data type as elements of sequence- 

pvar. In each active processor, contains a copy of the first ele¬ 
ment of sequence-pvar that matched item-pvar. Returns the 
value of the :return-value-if-not-found argument in proces¬ 
sors where no match is found. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp find function, with an 
additional keyword, :return-value-if-not-found. 

In each processor, the function find!! searches sequence-pvar for elements that 
match item-pvar. It returns a pvar containing a copy of the first matching element 
found in each processor. In any processor failing the search, the value of the 
:return-value-if-not-found argument is returned. 

Elements of sequence-pvar are tested against item-pvar with the eql!! operator un¬ 
less another comparison operator is supplied as either of the :test or :test-not ar¬ 
guments. The keywords :test and :test-not may not be used together. 

The keyword :from-end takes a boolean pvar that specifies from which end of se¬ 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords: start and -.end define a subsequence to be operated on 
in each processor. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element ofse- 
quence-pvar. 

The keyword argument to :return-value-if-not-found must be a pvar and defaults 
to nil! !. The value of this pvar is returned in any processor where the search is not 
successful. 
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find!! 


Examples- 

(find!! (!! 9) (!! #(149))) <=> (!! 9) 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

The functions find—if !! and find—if—not! ! are similar. They search sequence-pvariox 
elements that either do or do not pass a supplied test. 

These functions are members of a group of similar sequence operators, 
listed below: 

count!! count-if!! count-if-not!! 

find!! find-if!! f ind-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute—if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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find—if!! [Function] 

Performs a parallel search on a sequence pvar, returning in each processor the first 
sequence element satisfying the supplied test. 

Syntax- 

find-if!! test sequence-pvar 

&key :from-end :start :end :key :return-value-if-not-found 


Arguments- 

test One-argument pvar predicate. Used to test elements of se¬ 

quence-pvar. 

sequence-pvar Sequence pvar. Contains sequences to be searched. 

:from-end Boolean pvar. Whether to begin search from end of sequence 

in all processors. Defaults to nil. 

.•start Integer pvar. Index, zero-based, of sequence element at which 

search starts in each processor. If not specified, search begins 
with first element. 

:end Integer pvar. Index, zero-based, of sequence element at which 

search ends in each processor. If not specified, search contin¬ 
ues to end of sequence. 

:key One-argument pvar accessor function. Applied to 

sequence-pvar before test is performed. 

:return-value-if-not-found 

Pvar expression. Value to return in processors where no ele¬ 
ment of sequence-pvar satisfies test. Default is nil!!. 


Returned Value- 

find-pvar Temporary pvar, of same data type as elements of sequence- 

pvar. In each active processor, contains a copy of the first ele¬ 
ment of sequence-pvar that satisfied test. Returns the value of 
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the :return-value-if-not-found argument in processors where 
no match is found. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp find-if function, with 
an additional keyword, :return-value-if-not-found. 

In each processor, the function find-if! ! searches sequence-pvar for elements satis¬ 
fying test. It returns a pvar containing a copy of the first matching element found in 
each processor. In any processor failing the search, the value of the 
:return-va!ue-if-not-found argument is returned. 

The keyword :from-end takes a boolean pvar that specifies from which end of se- 
quence-pvcir in each processor the operation will take place. 

Arguments to the keywords: start and :end define a subsequence to be operated on 
in each processor. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 


Examples 


(find-if!! 'evenp!! (!! #(1 4 9))) <=> (!! 4) 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 
count!! count-if!! count-if-not!! 

find!! find-if!! find—if—not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute—if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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find-if-not!! [Function] 

Performs a parallel search on a sequence pvar, returning in each processor the first 
sequence element failing the supplied test. 


Syntax- 

find-if-not! ! test sequence-pvar 

&key :from-end .-start :end :key :return-value-if-not-found 


Arguments- 

test One-argument scalar predicate. Used to test elements of se¬ 

quence-pvar. 

sequence-pvar Sequence pvar. Contains sequences to be searched. 

:from-end Boolean pvar. Whether to begin search from end of sequence 

in all processors. Defaults to nil. 

: start Integer pvar. Index, zero-based, of sequence element at which 

search starts in each processor. If not specified, search begins 
with first element. 

:end Integer pvar. Index, zero-based, of sequence element at which 

search ends in each processor. If not specified, search contin¬ 
ues to end of sequence. 

:key One-argument pvar accessor function. Applied to 

sequence-pvar before test is performed. 

:return-value-if-not-found 

Pvar expression. Value to return in processors where no ele¬ 
ment of sequence-pvar fails test. Default is nil!!. 


Returned Value- 

find-pvar Temporary pvar, of same data type as elements of sequence- 

pvar. In each active processor, contains a copy of the first ele¬ 
ment of sequence-pvar that failed test. Returns the value of the 
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:return-value-if-not-found argument in processors where no 
match is found. 


Side Effects-- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp find-if-not function, 
with an additional keyword, :return-va!ue-if-not-found. 

In each processor, the function find-if-not! ! searches sequence-pvar for elements 
failing test. It returns a pvar containing a copy of the first matching element found 
in each processor. In any processor failing the search, the value of the 
:return-value-if-not-found argument is returned. 

The keyword :from-end takes a boolean pvar that specifies from which end of se¬ 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords: start and :end define a subsequence to be operated on 
in each processor. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 

The keyword argument to :return-value-if-not-found must be a pvar and defaults 
to nil !!. The value of this pvar is returned in any processor where the search is not 
successful. 


Examples 


(find-if-not!! 'evenp!! (!! #(1 49))) <=> (!! 1) 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 
count!! count-if!! count-if-not!! 

find!! find—if!! find—if—not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute—if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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float!! [Function] 

Converts the numeric values of a specified pvar into a floating-point format. 


Syntax- 

float!! numeric-pvar &optional float-format-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Pvar to be converted to floating¬ 
point format. 

float-format-pvar Floating-point pvar. If supplied, determines the floating-point 
format into which numeric-pvar is converted. Defaults to a 
pvar in single-float format. 


Returned Value- 

float-pvar Temporary numeric pvar. In each active processor, contains a 

copy of the value of numeric-pvar converted to floating-point 
format. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function converts any non-complex numeric pvar to a floating-point represen¬ 
tation. In processors where number-pvar already contains floating-point numbers, 
those numbers are simply copied; elsewhere, single-float numbers are produced. 
When the optional argument float-format-pvar is given, number-pvar is converted 
to a matching floating-point format (single- or double-precision). 
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Examples 


Notes 


References- 

See also these related floating-point operations: 


fceiling!! 

f floor!! 


float-sign!! 

scale-float!! 

fround!! 

ftruncate!! 
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float-epsilon!! [Function] 

Returns a pvar containing the smallest positive floating-point value representable in 
the format of the supplied floating-point pvar. 


Syntax- 

float-epsilon! ! floating-point-pvar 


Arguments- 

floating-point-pvar 

Floating-point pvar. Determines format of returned pvar. 


Returned Value- 

epsilon-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the smallest positive value representable in the same for¬ 
mat as the corresponding value of floating-point-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, the value returned by float-epsilon!! is the smallest positive 
floating-point number, e, that can be represented by the CM in the same floating 
point format as floating-point-pvar and for which 

(not (= (float 1 e) (+ (float l e) e ))) 

is true when evaluated. 
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Examples- 

Notes- 

References- 

See also these related floating-point pvar limit functions: 
least-negative-float!! least-positive-float!! 

most-negative-float!! most-positive-float!! negative-float-epsilon!! 
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float-sign!! [Function] 

Returns a unit value floating-point pvar with the same sign as the supplied pvar. 


Syntax- 

float-sign!! sign-pvar Aoptiona! value-pvar 


Arguments- 

sign-pvar Floating-point pvar. Determines sign of result. 

value-pvar Floating-point pvar. Determines absolute value of result. De¬ 

faults to (!! 1.0). 


Returned Value- 

sign-value-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains a floating-point value with the same sign as sign-pvar and 
the same absolute value as value-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a floating-point pvar result with the same sign as sign-pvar 
and the same absolute value as value-pvar. 
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Examples- 

(float-sign!! (!! 0.08)) <=> (!! 1.0) 

(float-sign!! (!! -0.08)) <=> (!! -1.0) 


Notes 


References- 

See also these related floating-point operations: 


fceiling!! 

ffloor!! 

float!! 

f round!! 

ftruncate!! 


scale-float!! 
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f loatp !! [Function] 

Performs a parallel test for floating-point values on the supplied pvar. 


Syntax- 

floatp!! pvar 


Arguments- 

pvar Numeric pvar. Pvar to be tested for floating-point values. 


Returned Value- 

floatp-pvar Temporary boolean pvar. Contains the value t in each active 

processor where the pvar contains a floating-point value, and 
nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function floatp. It returns the 
value t in each active processor where the pvar contains a floating-point value, and 
nil in all other active processors. 
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Examples 


Notes 


References 


See also these related pvar data type predicates: 


booleanp!! 

front-end-p!! 

numberp!! 

typep!! 


characterp!! 

integerp!! 

string-char-pM 


complexp!! 

structurep!! 
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floor!! [Function] 

Performs a parallel floor operation on the supplied pvar(s). 


Syntax- 

floor!! numeric-pvar &optional divisor-numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Value for which the floor is calcu¬ 
lated. 

divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di¬ 
vided by divisor-numeric-pvar before the floor is taken. 


Returned Value- 

floor-pvar Temporary integer pvar. In each active processor, contains the 

floor of numeric-pvar, divided by divisor-numeric-pvar if 
supplied. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function floor, except that only 
one value—the floor of the quotient of numeric-pvar and divisor-numeric-pvar—is 
computed and returned. 


459 




floor!! 


*Lisp Dictionary 


Examples 


Notes 


References- 

See also these related rounding operations: 
ceiling!! round!! truncate!! 

See also these related floating-point rounding operations: 

fceiling!! ffloor!! fround!! ftruncate!! 
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front-end!! [Function] 

Returns a pvar whose values are references to a front-end object. 

Syntax- 

front-end! ! scalar-object 

Arguments- 

scalar-object Front-end scalar object. Object referenced by the returned 
pvar. 

Returned Value- 

front-end-pvar Temporary pvar. In each active processor, contains a reference 
rto the front-end object scalar-object. 

L _,- 7 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a pvar of type (pvar front-end). Note that a general pvar— 
that is, a pvar of type (pvar t)— can store a front-end pvar. 

Front-end pvars may be passed as arguments only to *Lisp operations that access, 
move, or compare data, but not to operations that combine or compute with data. 
Operations that may take front-end pvar arguments include 

eq!! if!! news!! 

pref!! pref *pset 

scan!! (with copy!!) *set setf (with pref) 

( 
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Examples-- 

Front-end pvars are useful for storing parallel data that has meaning when taken in 
combination with other data stored on the Connection Machine. For example, a 
front-end pvar can be used to store the symbolic names of a number of test sub¬ 
jects, such as simulated biological organisms. The expression 

(*defvar names (front-end!! 'nothing)) 

defines a front-end pvar with symbolic values (initially, every value in names is a 
reference to the symbol nothing). Symbolic names can be stored into a front-end 
pvar by using setf with pref, as in 

(setf (pref names 0) 'mutant-79) 

Computations on other pvars can use the values stored in a front-end pvar for dis¬ 
play or reference purposes, as in the examples below. 

(*defun survivors () 

(*when survived-simulated-catastrophe 
(format t "The survivors are: 

(do-for-selected-processors (proc) 

(format t (pref names proc))))) 


(*defun describe-microbe (bug-name) 

(♦when (eq!! names (front-end!! bug-name)) 

(format-description-for-selected-microbes))) 


Notes 


References 


See also the pvar allocation and deallocation operations 
allocate!! array!! 

"deallocate *dea!locate-*defvars "defvar 

•let * let* 

make-array!! typed-vector!! vector!! 
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front-end~p!! [Function] 

Performs a parallel test for front-end references on the supplied pvar. 


Syntax- 

front-end-p!! pvar 


Arguments- 

pvar Pvar expression. Tested in parallel for front-end reference val¬ 

ues. 


Returned Value- 

front-endp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the value of pvar is a front-end reference. Con¬ 
tains nil in all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function tests pvar and returns t in those processors containing pointers to a 
front-end object and nil elsewhere. Note that if pvar is a general pvar, t could be 
returned in some processors while nil is returned in others. 
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Examples- 

(*defvar names (front-end!! 'nothing)) 
(front-end-p!! names) => t 


Notes 


References 


See also these related pvar data type predicates: 
booleanp!! characterp!! 


floatp!! 

numberp!! 

typep!! 


integerp!! 

string-char-p!! 


complexp!! 

structurep!! 
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fround!! [Function] 

Performs a parallel floating-point round operation on the supplied pvar(s). 


Syntax- 

fround!! numeric-pvar &optional divisor-numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Value for which the floating-point 
round is calculated. 

divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di¬ 
vided by divisor-numeric-pvar before rounding is done. 


Returned Value- 

fround-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the floating-point rounded value of numeric-pvar, di¬ 
vided by divisor-numeric-pvar if supplied. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function fround. The 
value returned by fround! ! is the same as that returned by round! !, except that the 
result in each processor is always a floating-point number rather than an integer. 
The following forms are equivalent: 

(fround!! data-pvar) <=> (float!! (round!! data-pvar)) 

The argument pvars may contain either integer or floating-point values. 
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Examples 


Notes 


References- 

See also these related rounding operations: 

ceiling!! floor!! round!! truncate!! 

See also these related floating-point operations: 

fceiling!! ffloor!! float!! 

float-sign!! ftruncate!! 

scale-float!! 
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ftruncate!! [Function] 

Performs a parallel floating-point truncation on the supplied pvar(s). 


Syntax- 

ftruncate!! numeric-pvar &optional divisor-numeric-pvcir 


Arguments- 

numeric-pvar Non-complex numeric pvar. Value for which the floating-point 
truncation is calculated. 

divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di¬ 
vided by divisor-numeric-pvar before truncation is done. 


Returned Value- 

ftruncate-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the floating-point truncated value of numeric-pvar, di¬ 
vided by divisor-numeric-pvar if supplied. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function ftruncate. 
The value returned by ftruncate! ! is the same as that returned by truncate! !, except 
that the result in each processor is always a floating-point number rather than an 
integer. The following forms are equivalent: 

(ftruncate!! data-pvar) <=> (float!! (truncate!! data-pvar)) 

The argument pvars may contain either integer or floating-point values. 
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Examples 


Notes 


References- 

See also these related rounding operations: 

ceiling!! floor!! round!! truncate!! 

See also these related floating-point operations: 

fceiling!! f floor!! float!! 

float-sign!! fround!! scale-float!! 
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*funcall [Macro] 

Applies a parallel function defined by *defun to a set of arguments. 

Syntax- 

*funcall function &rest arguments 

Arguments- 

function Symbol or function object. Function to call. 

arguments Scalar or pvar expressions. Arguments to pass to function. 

Returned Value- 

retumed-value Scalar or pvar value. Value returned by function. 

Side Effects- 

None other than those of the supplied function. 

Description- 

This is used just as Common Lisp’s funcall, but with functions defined using 

*defun. 
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Examples 


(♦defun difference!! (pvarl pvar2) (-!! pvarl pvar2)) 
(♦funcall 'difference!! (!! 3) (!! 4))) <=> (!! -1) 


Notes- 

Errors: 

It is an error to use Common Lisp’s funcall with a function defined using 

*defun. 


References- 

See also the following related operations: 


•apply 

•defun 


•trace 

un*defun 

•untrace 
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gcd!! [Function] 

Computes in parallel the greatest common denominator of the supplied integer pvars. 


Syntax- 

gcd!! &rest integer-pvars 


Arguments- 

integer-pvars Integer pvars. Pvars for which gcd is to be calculated. 


Returned Value- 

gcd-pvar Temporary integer pvar. In each active processor, contains the 

greatest common denominator for the corresponding values of 
the integer-pvars. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes zero or more integer pvars and computes, in each processor, 
the greatest common divisor of all of the argument pvar components in that proc¬ 
essor. The function always returns a non-negative integer pvar. Specifically: 

■ If no arguments are given, 0 is returned in each processor. 

■ If one argument is given, its absolute value is returned in each processor. 

■ If two arguments are given, the gcd of the two pvar components is returned 
in each processor. 

■ If three or more arguments are given, the behavior is: 

(gcd! ! a b c ... z) <=> (gcd! ! (gcd! ! a b) c ... z) 
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Examples- 

Notes- 

References- 
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graphic-char-p!! [Function] 

Performs a parallel test for graphic characters on the supplied pvar. 


Syntax- 

graphic-char-p!! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for alphabetic characters. 

Must be a character pvar, a string-char pvar, or a general pvar 
containing only elements of type character or string-char. 

Returned Value- 

graphic-charp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is 
an graphic character. Contains nil in all other processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns t in those processors where character-pvar contains a print¬ 
ing character and nil elsewhere. On the Connection Machine, only characters with 
ASCII values ranging from 32 to 127, inclusive, are considered graphic, printing 
characters. Any character pvar with a bits field of non-zero value is not a graphic 
character pvar. 
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Examples- 

Notes- 

References- 
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gray-code-from-integer!! [Function] 

Performs a parallel conversion from integers to Gray code values on the supplied pvar. 


Syntax- 

gray-code-from-integer! ! integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar to be converted to gray code values. Must 

contain unsigned integers. 


Returned Value- 

gray-code-pvar Temporary unsigned integer pvar. In each active processor, 
contains the gray code representation of the corresponding 
value of integer-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function converts each integer component of the integer-pvar argument into a 
Gray code representation. Binary reflected Gray code is used. 
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Examples 

Notes — 


References- 

See also the related function integer-from-gray-code!!. 
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grid [ Function ] 

Creates and returns an address object containing the supplied integers as grid (NEWS) 
coordinates. 

Syntax- 

grid Arest integers 

Arguments- 

integers Scalar integers. Coordinates for the returned address object. 

Returned Value- 

address-object Address object, allocated on front end. Contains the supplied 
integers as grid (NEWS) coordinates. 

Side Effects- 

None. 

Description- 

This function creates and returns a front-end address object that contains the 
specified integers as grid (NEWS) coordinates. 
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Examples- 

(*cold-boot :initial-dimensions '(8 4)) 

(pref (self-address!!) (grid!! 4 2)) <=> 18 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth address-plus-nth!! 

address-rank address-rank!! 

grid!! 

grid-relative!! self!! 
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grid!! [Function] 

Creates and returns an address-object pvar with grid (NEWS) coordinates specified by 
the supplied pvars. 


Syntax- 

grid!! &rest integer-pvars 


Arguments- 

integer-pvars Integer pvars. Coordinates for the returned address-object 
pvar. 


Returned Value- 

address-object-pvar 

Temporary address-object pvar. In each active processor, con¬ 
tains an address object with the coordinates specified by the 
corresponding values of the integer-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function creates and returns a pvar of address objects containing the speci¬ 
fied integer-pvars as grid (NEWS) coordinates. 
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Examples- 

(*cold-boot :initial-dimensions '(8 4)) 

(pref!! (self-address!!) (grid!! (!! 4) (!! 2))) <=> (!! 18) 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth address-plus-nth!! 

address-rank address-rank!! 

grid 

grid-relative!! self!! 
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grid-from-cube-address [Function] 

Converts a send (cube) address into a grid (NEWS) coordinate in the current VP set for 
a specified dimension. 


Syntax- 

grid-from-cube-address send-address dimension 


Arguments- 

send-address Integer. Send address to be converted. 

dimension Integer. Number of the dimension for which the coordinate 

corresponding to send-address is to be returned. Zero-based. 


Returned Value- 

coordinate Integer. Grid (NEWS) coordinate in the current VP set, of the 

processor specified by send-address along the specified dimen¬ 
sion. 

Side Effects- 

None. 


Description- 

This function takes a send-address and returns the grid (NEWS) coordinate for the 
specified dimension in the current VP set. This function executes entirely in the 
front-end computer. 

The send-address argument is a single integer representing the send address of a 
single processor. It is translated into a single integer representing the grid address 
of that processor along the specified dimension. 
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The send-address argument must be a non-negative integer within the current ma¬ 
chine configuration’s range of send addresses. This range extends from zero 
through (1- *number-of-processor$-limit*), inclusive. 

The dimension argument must be a non-negative integer between zero and one less 
than the rank of the current machine configuration. 


Examples- 

Assume a four-dimensional machine configuration has been defined, and that the 
processor referenced by send address 6534 has a grid address of (6 52 75 259). 

(grid-from-cube-address 6534 2) =>75 

Here, the grid address component corresponding to dimension 2 is returned. To 
obtain all the grid address components for a given send-address, call grid-from- 
cube-address repeatedly, specifying a different dimension each time. 


Notes- 

Note that the send (cube) address corresponding to a particular grid address is not 
predictable from the grid address values alone. It also depends on the geometry of 
the current VP set, on the number of physical processors attached, and on the sys¬ 
tem software version in use. In particular, the relationship between send and grid 
addresses in the *Lisp simulator is different from that of the actual CM-2 hard¬ 
ware. 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address, cube-from-vp-grid-address, grid-from-cube-address, and grid- 
from-vp-cube-address. 


References 


See also these related send and grid address translation operators: 


cube-from-grid-address 
cube-from-vp-grid-address 
grid-from-cube-address!! 
grid-from-vp-cube-address 
self-address!! 


cube-from-grid-address!! 

cube-from-vp-grid-address!! 

grid-from-vp-cube-address!! 

self-address-grid!! 
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grid-from-cube-address!! 


grid-from-cube-address!! [Function] 

Performs a parallel conversion from send (cube) addresses into grid (NEWS) coordi¬ 
nates in the current VP set. 


Syntax- 

grid-from-cube-address!! send-address-pvar dimension-pvar 


Arguments- 

send-address-pvar Integer pvar. Send address to be translated. 

dimension-pvar Integer pvar. Number of the dimension for which the coordi¬ 
nate corresponding to send-address-pvar is to be returned. 
Zero-based. 


Returned Value- 

coordinate-pvar Temporary integer pvar. In each processor, contains the grid 
(NEWS) coordinate in the current VP set, of the processor spe¬ 
cified by send-address-pvar along the dimension specified by 
dimension-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes a send-address-pvar and returns a pvar containing the grid 
(NEWS) coordinate in the current VP set for the specified dimension-pvar for each 
selected processor. 

In each processor, this function translates the send (cube) address specified that 
processor’s value of send-address-pvar into a corresponding grid address along the 
dimension specified by the local value of dimension-pvar. This is the parallel 
equivalent of grid-from-cube-address. 
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The send-address-pvar argument must be pvar containing a non-negative integer 
in each processor. Each of these integers must be within the range zero through 
(1- *number-of-processors-limit*), inclusive. 

The dimension-pvar argument must be a pvar containing, in each processor, a non¬ 
negative integer between zero and the rank of the current machine configuration 
minus one. 

The return value of grid-from-cube-address!! is an integer pvar containing non¬ 
negative integers. In each processor the integer returned is the dimension-pvar grid 
address component of the processor referenced by send-address-pvar. 


Examples- 

Assume a four-dimensional machine configuration has been defined, and that the 
processor referenced by send address 6534 has a grid address of (6 52 75 259). 

(grid-from-cube-address!! (!! 6534) (!! 2)) => (!! 75) 

Here, the grid address component corresponding to dimension 2 is returned in all 
active processors. 

A more extensive example of grid-from-cube-address!! is detailed below. 
(*cold-boot :initial-dimensions '(128 128)) 

(ppp (self-address!!) :mode :grid :end '(4 4) :format "~3D ") 

0 12 3 

8 9 10 11 

16 17 18 19 

24 25 26 27 

(PPP (grid-from-cube-address!! (self-address!!) (!! 0)) 

:mode :grid :end '(4 4) :format "~3D ") 

0 12 3 

0 12 3 

0 12 3 

0 12 3 
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grid-from-cube-address!! 


(PPP (grid-from-cube-address!! (self-address!!) (!! 1)) 
:mode :grid ;end '(4 4) :format "~3D ") 

0 0 0 0 

1111 
2 2 2 2 

3 3 3 3 


Notes- 

Note that the send (cube) address corresponding to a particular grid (NEWS) ad¬ 
dress is not predictable from the grid (NEWS) address values alone. It also depends 
on the geometry of the current VP set, on the number of physical processors at¬ 
tached, and on the system software version in use. 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address!!, cube-from-vp-grid-address!!, grid-from-cube-address!!, and 
grid-from-vp-cube-addressM. 


References 


See also these related send and grid address translation operators: 


cube-from-grid-address 

cube-from-vp-grid-address 

grid-from-cube-address 

grid-from-vp-cube-address 

self-address!! 


cube-from-grid-address!! 

cube-from-vp-grid-address!! 

grid-from-vp-cube-address!! 
self-address-grid!! 
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grid-from-vp-cube-address [Function] 

Converts a send (cube) address into a grid (NEWS) coordinate for the specified VP set. 


Syntax- 

grid-from-vp-cube-address vp-set send-address dimension 


Arguments- 

vp-set VP set object. VP set in which the supplied send-address is 

converted. 

send-address Integer. Send address to be converted. 

dimension Integer. Number of the dimension for which the coordinate 

corresponding to send-address is to be returned. Zero-based. 

Returned Value- 

coordinate Integer. Grid (NEWS) coordinate in the specified vp-set, of the 

processor specified by send-address along the specified dimen¬ 
sion. 

Side Effects- 

None. 


Description- 

This function translates send-address, an integer representing the send address of 
a single processor in vp-set, into an integer representing the grid address of that 
processor along the specified dimension in vp-set. 

The send-address argument must be a non-negative integer within vp-set' s range of 
send addresses. 
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The dimension argument must be a non-negative integer between zero and one less 
than the rank of vp-set's dimensions. 


Examples- 

Assume that my-vp has a four-dimensional geometry, and assume that the proc¬ 
essor referenced by send address 6534 has a grid address of (6 52 75 259) within the 
geometry of my-vp. 

(grid-from-vp-cube-address my-vp 6534 2) => 75 

Here, the grid address component corresponding to dimension 2 is returned. To 
obtain all the grid address components for a given send-address in a given vp-set, 
call grid-from-vp-cube-address repeatedly, specifying a different dimension each 
time. 


Notes- 

Note that the send (cube) address corresponding to a particular grid (NEWS) ad¬ 
dress is not predictable from the grid (NEWS) address values alone. It also depends 
on the geometry of the current VP set, on the number of physical processors at¬ 
tached, and on the system software version in use. 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address. cube-from-vp-grid-address, grid-from-cube-address, and grid- 
from-vp-cube-address. 


References 


See also these related send and grid address translation operators: 


cube-from-grid-address 
cube-from-vp-grid-address 
grid-from-cube-address 
grid-from-vp-cube-address!! 
seif-address!! 


cube-from-grid-address!! 

cube-from-vp-grid-address!! 

grid-from-cube-address!! 

self-address-grid!! 
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grid-from-vp-cube-address!! 


grid-from-vp-cube-address!! [Function] 

Performs a parallel conversion of send (cube) addresses into grid (NEWS) coordinates 
for the specified VP set. 


Syntax- 

grid-from-vp-cube-address!! vp-set send-address-pvar dimension-pvar 


Arguments- 

vp-set VP set object. VP set for which grid (NEWS) coordinates are 

returned. 

send-address-pvar Integer pvar. Send address to be translated. 

dimension-pvar Integer pvar. Number of the dimension for which the coordi¬ 
nate corresponding to send-address-pvar is to be returned. 
Zero-based. 


Returned Value- 

coordinate-pvar Temporary integer pvar. In each processor, contains the grid 
(NEWS) coordinate in the specified vp-set, of the processor 
specified by send-address-pvar along the dimension specified 
by dimension-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function performs a parallel conversion of send (cube) addresses into grid 
(NEWS) coordinates for the specified vp-set. This is the parallel equivalent of grid- 
from-vp-cube-address. 
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The value of send-address-pvar in each processor is assumed to be an integer rep¬ 
resenting the send address of a single processor in vp-set. This is translated into an 
integer representing the grid address of that processor along the dimension speci¬ 
fied by the value of dimension-pvar. 

The send-address-pvar must be a pvar containing a non-negative integer in each 
processor. Each of these integers must be within the range of valid send addresses 
for vp-set. 

The dimension-pvar argument must be a pvar containing, in each processor, a non¬ 
negative integer between zero and the rank of vp-sefs dimensions minus one. 


Examples- 

Assume the VP set my-vp has a four-dimensional machine geometry, and that the 
processor referenced by send address 6534 has a grid address of (6 52 75 259) in 

my-vp. 


(grid-from-vp-cube-address!! 

my-vp (!! 6534) (M2)) => (!! 75) 

Here, the grid address component corresponding to dimension 2 in my-vp is re¬ 
turned in all active processors. 


Notes- 

Note that the send (cube) address corresponding to a particular grid (NEWS) ad¬ 
dress is not predictable from the grid (NEWS) address values alone. It also depends 
on the geometry of the current VP set, on the number of physical processors at¬ 
tached, and on the system software version in use. 

It is an error to rely on a specific, fixed relation between send and grid addresses 
except as provided by *Lisp address conversion functions such as cube-from- 
grid-address!!, cube-from-vp-grid-address!!, grid-from-cube-address!!, and 
grid-from-vp-cube-address!!. 
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grid-from-vp-cube-address!! 


References- 

See also these related send and grid address translation operators: 

cube-from-grid-address cube-from-grid-address!! 

cube-from-vp-grid-address cube-from-vp-grid-address!! 
grid-f rom-cube-address grid-from-cube-address!! 

grid-from-vp-cube-address 

self-address!! self-address-grid!! 
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grid-relative!! [Function] 

Returns an address-object pvar containing, for each processor, the grid (NEWS) coor¬ 
dinates of the processor a specified distance away along each dimension of the geome¬ 
try of the current VP set. 


Syntax- 

grid-relative!! &rest relative-coord-pvars 


Arguments- 

relative-coord-pvars 

Integer pvars. Specify relative distance along each dimension 
of the current VP set. 


Returned Value- 

address-object-pvar 

Temporary address-object pvar. In each active processor, con¬ 
tains an address object with the absolute grid (NEWS) coordi¬ 
nates of the processor specified by relative-coord-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is equivalent to 


(grid!! 

( + ! ! 

integer-pvar-0 

(self-address-grid!! 

( ! ! 

0))) 


(+! ! 

integer-pvar-1 

(self-address-grid!! 

(! ! 

1))) 


(+! ! 

integer-pvar-2 

(self-address-grid!! 

(! ! 

2))) 


. . . ) 
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grid-relative!! 


Examples 


Notes 


References- 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth address-plus-nth!! 

address-rank address-rank!! 

grid grid!! 

self!! 
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help 

Prints out a brief description of a *Lisp symbol. 

Syntax- 

help &optional symbol 

Arguments- 

symbol *Lisp symbol. Symbol about which to print description. 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

Prints a brief description of the supplied symbol, or, if no symbol is supplied, a 
message describing where to find information about *Lisp. 


[Function] 


Description- 

When given no argument, help prints a message describing where to find informa¬ 
tion about *Lisp. When given a symbol defined by the *Lisp language, help prints 
information about the symbol, including whether it is a function, a macro, a func¬ 
tion defined by *defun, or a variable, and whether the symbol is new as of Connec¬ 
tion Machine System Software Version 5.0. 
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Examples - 

Notes- 

References 
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*if [Macro] 

Evaluates *Lisp forms with the currently selected set bound according to the logical 
value of a pvar expression. 

Syntax- 

*if test-pvar then-form &optional else-form 

Arguments 

test-pvar 
then-form 

else-form 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

Temporarily restricts the currently selected set during the evaluation of then-form 
and else-form. 

Description- 

This operator is analogous to the Common Lisp conditional if, with two essential 
differences. Both then-form and else-form are evaluated—in mutually exclusive 
sets of processors. Also, unlike Common Lisp’s if, the *if macro returns no values 
and is executed only for its side effects. 


Pvar expression. Selects processors in which to evaluate then- 
form and else-form. 

Pvar expression. Evaluated with the currently selected set re¬ 
stricted to those processors for which the value of test-pvar is 
not nil. 

Pvar expression. If supplied, evaluated with the currently se¬ 
lected set restricted to those processors in which the value of 
test-pvar is nil. 
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The then-form argument is evaluated with the currently selected set bound to those 
processors in which test-pvar evaluates to a non-nil value. The optional else’form 
argument is evaluated with the currently selected set bound to those processors in 
which test-pvar evaluates to a nil value. 


Examples- 

(*defvar winners) 

(*defvar losers) 

(*if (zerop!! (random!! (!! 100))) 

(♦set winners (!! 1)) 

(♦set losers (!! 1))) 

Important: Even if no processors are selected by test-pvar , both then’form and 
else’form are evaluated. 

(setq a 5 b 7) 

(♦if nil!! (setq a 7) (setq b 5)) 
a => 7 
b => 5 

In many cases, the macros *if and if!! can be used interchangeably. For example, 
these two expressions are equivalent, although in this case the latter expression is 
preferred as being more concise: 

(♦if (evenp!! data-pvar) 

(♦set bit-pvar (!! 1)) 

(♦set bit-pvar (!! 0))) 

<=> 

(♦set bit-pvar (if!! (evenp!! data-pvar) (!! 1) (!! 0))) 

As with all processor selection operators, calls to *if may be nested. Each call to *if 
subselects from the currently selected set, whether the selected set is the entire set 
of processors attached, or a subset selected by an enclosing operator. For example, 

(♦defvar result (!! 0)) 

(♦if (evenp!! (self-address!!)) 

(♦if (zerop!! (mod!! (self-address!!) (!! 4))) 

(♦set result (!! 4)) 

(♦set result (!! 2))) 

(♦set result (!! 1))) 

(ppp result) => 4121412141... 
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*if 


Notes- 

Usage Note: 

Forms such as throw, return, return-from, and go may be used to exit an exter¬ 
nal block or looping construct from within a processor selection operator. 
However, doing so will leave the currently selected set in the state it was in at 
the time the non-local exit form is executed. To avoid this, use the *Lisp macro 
with-css-saved. For example, 

(block division 
(with-css-saved 

(*if (>!! y (!! 0)) 

(if (*or (=!! (!! 0) x) ) 

(return-from division nil) 

(/!! y x))))) 

Here return-from is used to exit from the division block if the value of x in any 
processor is zero. When the with-css-saved macro is entered, it saves the state 
of the currently selected set. When the code enclosed within the with-css- 
saved exits for any reason, either normally or via a call to a non-local exit opera¬ 
tor like return-from, the currently selected set is restored to its original state. 

See the dictionary entry for with-css-saved for more information. 

Style Note: 

As with the Common Lisp if operator, if no else-form is present, it is stylistical¬ 
ly better to use the ‘when operator. Additionally, if the test-pvar is of the form 

(*if (not!! test) ... 

it is preferable to use the ‘unless operator, as in 

(♦unless test ... 
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References- 

The *Lisp operator if!! behaves exactly like ‘if, but returns a pvar based on the 
evaluation of its arguments. See the dictionary entry for if !! for more information. 

See also the related operators 

‘all ‘case case!! *cond cond!! 

*ecase ecase!! ‘unless ‘when with-css-saved 
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if!! [Macro] 

Returns a pvar obtained by evaluating *Lisp forms with the currently selected set 
bound according to the logical value of a pvar expression. 


Syntax- 

if!! test-pvar then-form &optional else-form 


Arguments- 

test-pvar Pvar expression. Selects processors in which to evaluate then- 

form and else-form. 

then-form Pvar expression. Evaluated with the currently selected set re¬ 

stricted to those processors for which the value of test-pvar is 
not nil. 

else-form Pvar expression. If supplied, evaluated with the currently se¬ 

lected set restricted to those processors in which the value of 
test-pvar is nil. Defaults to nil!!. 


Returned Value- 

then-else-pvar Temporary pvar. Contains the value of then-form in all active 
processors where test-pvar evaluates to a non-nii value. Con¬ 
tains the value of else-form in all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This operator is analogous to the Common Lisp conditional if, with one essential 
difference. Both then-form and else-form are evaluated, in mutually exclusive sets 
of processors. 
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The then-form argument is evaluated with the currently selected set bound to those 
processors in which test-pvar evaluates to a non-nil value. The optional else-form 
argument is evaluated with the currently selected set bound to those processors in 
which test-pvar evaluates to a nil value. 

The if! ! macro returns a pvar that contains the value of then-form in all processors 
in which test-pvar is non-nil, and the value of else-form in all processors in which 
test-pvar is nil. 

(if!! question-pvar yes-pvar no-pvar) <=> 

(♦let (result) 

(♦when question-pvar (*set result yes-pvar)) 

(♦unless question-pvar (*set result no-pvar)) 
result) 


Examples- 

An example that demonstrates the usefulness of if!! is the following function to 
take the absolute value of a pvar: 

(defun my-abs!! (pvar) 

(if!! (>!! pvar (!! 0)) 
pvar 

(-!! pvar))) 


Important: Even if no processors are selected by test-pvar, both then-form and 
else-form are evaluated. For example, 


(setq a 5 b 7) 

(if!! nil!! 

(progn (setq a 7) (!! 0)) 

(progn (setq b 5) (!! 1))) => (!! 1) 

a => 7 
b => 5 
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In many cases, the macros *if and if!! can be used interchangeably. For example, 
these two expressions are equivalent, although in this case the latter expression is 
preferred as being more concise: 

(*if (evenp!! data-pvar) 

(*set bit-pvar (!! 1)) 

(*set bit-pvar (!! 0))) 

(*set bit-pvar (if!! (evenp!! data-pvar) (!! 1) (!! 0))) 

As with all processor selection operators, calls to if!! may be nested. Each call to if!! 
subselects from the currently selected set, whether the selected set is the entire set 
of processors attached, or a subset selected by an enclosing operator. For example, 

(*defvar result (!! 0)) 

(*set result 

(if!! (evenp!! (self-address!!)) 

(if!! (zerop!! (mod!! (self-address!!) (!! 4))) 

(! ! 4) 

(!! 2 )) 

(!! D) 

(ppp result) => 4121412141... 


Notes 


References- 

The *Lisp operator *if behaves exactly like if!!, but does not return a pvar. See the 
dictionary entry for *if for more information. 

See also the related operators 

*all 

"case case!! 

*cond cond!! 

*ecase ecase!! 

‘unless *when 

with-css-saved 
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imagpart!! [Function] 

Extracts the imaginary component from a complex pvar. 


Syntax- 

imagpart!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar from which imaginary component is 
extracted. 


Returned Value- 

imagpart-pvar Temporary numeric pvar. In each active processor, contains 
the imaginary component of the corresponding value of 
numeric-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a temporary pvar containing in each processor the imaginary 
component of the complex value in numeric-pvar. Note that numeric-pvar need not 
be explicitly a complex-valued pvar. Non-complex values are automatically 
coerced into complex values with a zero imaginary component. 
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Examples 


Notes 


References 


See also these related complex pvar operators: 
absl! cis!! 

conjugate!! phase!! 


complex!! 

realpart!! 
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*incf [Macro] 

Destructively increments each value of the supplied pvar. 

Syntax- 

*incf numeric-pvar &optional value-pvar 

Arguments- 

numeric-pvar Pvar expression. Pvar to be incremented. 

value-pvar Numeric pvar. Amount to add to numeric-pvar. Defaults to 

(!! 1). 


Returned Value- 

nil Evaluated for side effect. 


Side Effects- 

Destructively increments each value of pvar by the corresponding value of value- 
pvar. 


Description- 

Increments each element of pvar by the corresponding value of value-pvar. The 
value-pvar argument defaults to (!! 1). 
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Examples- 

(*incf count-pvar (!! 3)) 


Notes- 

Usage Note: 

A call to the *incf macro expands as follows: 

(*incf data-pvar (!! 4)) 

==> 

(*setf data-pvar (+!! data-pvar (!! 4))) 

For this reason, the numeric-pvar must be a modifiable pvar, such as a permanent, 
global, or local pvar. It is an error to supply a temporary pvar as the numeric-pvar 

to *incf. 


References- 

See also the related macro *decf. 

The function 1+!! can be used to non-destructively perform a addition by 1 on its 
argument pvar. See the dictionary entry on 1+!! for more information. 
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initialize-character [Function] 

Sets bit widths of *Lisp character attributes. If used, must be called prior to calling 

*cold-boot. 


Syntax- 

initialize-character &key :code -bits :font :front-end-p :constantp 


Arguments- 


:code 

Integer. Number of bits to allocate for code attribute. 

: bits 

Integer. Number of bits to allocate for bits attribute. 

:font 

Integer. Number of bits to allocate for font attribute. 

:front-end-p 

Boolean value. Whether to directly copy character attribute 
widths used on the front end. 

:constantp 

Boolean value. Asserts whether or not the supplied values will 
remain constant for every succeeding call to * cold-boot. Used 
for optomization purposes by the *Lisp compiler. 


Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

Sets the values of the following global variables: 

■ *char-bits-length 

■ *char-bits-limit 

■ *char-code-length 

■ *char-code-limit 
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■ *char-font-length 

■ *char-font-Iimit 

■ ‘character-length 

■ ‘character-limit 

Determines whether the *Lisp compiler will assume that the bit widths of *Lisp 
character fields do not change. 


Description- 

This function sets the values of the *Lisp character attributes, which are stored in 
global character variables. The initialize-character function must be called before 
‘cold-boot is invoked, because these attributes are set when the machine is cold 
booted, not when the call to initialize-character is made. 

The keywords :code, :bits, and :font take integer values specifying how many bits 
will be allocated for each attribute of any character pvar. The defaults are :code 8, 
:bits 4, and :font 4. 

The value for :code must be greater than or equal to 7. 

The value for :bits must be greater than 0. 

The value for :font must be greater than or equal to 0. 

The keyword :front-end-p takes either t or nil as a value, defaulting to nil. It deter¬ 
mines whether character pvar attribute widths should be copied from the format 
being used on the front end machine. If :f ront-end-p is t, the global character vari¬ 
ables are set to match the character storage format of the front end machine. 

The keyword :constantp takes a boolean value. This is used to assert whether or 
not the sizes of character attributes will remain constant across execution sessions. 
The *Lisp compiler uses this distinction to choose between producing compiled 
code that uses the global character variables and producing compiled code that 
substitutes hard coded values for these variables. Code compiled with :constantp t 
will run reliably only when the character attributes are the size specified at compile 
time. Code compiled with :constantp nil need not be recompiled to operate reliably 
with different character attribute sizes. 
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Examples- 

Notes- 

References- 

For a discussion of Lisp character attributes, see the Characters chapter of 
Common Lisp: The Language. 

See also the Connection Machine initialization function *cold-boot. 

See also the initialization-list functions add-initialization and delete-initialization. 

See also the related character pvar attribute operators: 

char-bit!! char-bits!! char-code!! 

char-font!! set-char-bit!! 
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int-char!! [Function] 

Converts the supplied integer pvar into an character pvar. 


Syntax- 

int-char!! integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar to be converted. 


Returned Value- 

character-pvar Temporary character pvar. In each active processor, contains 
the character corresponding to the value of integer-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the converse of char-int !!. It converts an integer pvar into a charac¬ 
ter pvar. The return value is a character pvar which, if given to char-int!!, will re¬ 
turn integer-pvar. 

The argument integer-pvar must be a non-negative integer pvar. 

The int-char!! function relies on the Connection Machine system’s encoding of 
characters. Results obtained from this function should not be expected to conform 
to results obtained from the Common Lisp function int-char run on front-end ma¬ 
chines. 
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Examples- 

Notes- 

References-- 

See also the related character/integer pvar conversion operators: 
char-code!! char—int!! code-char!! 

digit-char!! int-char!! 
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integer-from-gray-code!! [Function] 

Performs a parallel conversion from Gray code values to integers on the supplied pvar. 


Syntax- 

integer-from-gray-code! ! gray-code-pvar 


Arguments- 

gray-code-pvar Integer pvar. Gray code value to be converted to a non-Gray- 
coded integer. 


Returned Value- 

integer-pvar Temporary integer pvar. In each active processor, contains the 

integer value corresponding to the Gray code value in integer- 
pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function treats each component of the argument pvar as a Gray-coded integer 
and converts it to a non-Gray-coded integer. The gray-code-pvar argument should 
contain unsigned integers.The function returns a pvar containing the unsigned re¬ 
sults. Binary reflected Gray code is used. 
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Examples 

Notes- 


References- 

See also the related function gray-code-from-integer!!. 
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*integer-length [*Defun] 

Determines the minimum bit-length needed to represent every value of an integer pvar. 


Syntax- 

•integer-length integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar for which minimum bit-length is deter¬ 

mined. 


Returned Value- 

integer-length Scalar integer. Minimum bit-length needed to represent every 
value of integer-pvar. 


Side Effects 

None. 


Description- 

This returns a scalar value that is the minimum bit-length needed to represent ev¬ 
ery integer value contined in integer-pvar. 
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Examples 


Notes 


References- 

See also the related global operators: 


and 

*logand 


logior 

‘logxor 

*max 

min 

*or 

*sum 

xor 
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integer-length!! [Function] 

Determines in parallel the minimum bit-length needed to represent each value of an 
integer pvar. 


Syntax- 

integer-length!! integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar for which minimum bit-lengths are deter¬ 
mined. 


Returned Value- 

length-pvar Temporary integer pvar. In each active processor, contains the 

minimum bit-length needed to represent the corresponding 
value of integer-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function determines, in each processor, the number of bits required to repre¬ 
sent that processor’s component of integer-pvar; it returns a non-negative integer 
pvar containing the results. 

A signed number requires (1+!! (integer-length!! integer-pvar)) bits to represent 
the integer in signed two’s-complement form. 
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Examples — 

For example, 


(integer-length!! 

(! 

0)) 

<=> 

(! 

0) 

(integer-length!! 

(! 

D) 

<=> 

(! 

1) 

(integer-length!! 

(! 

3)) 

A 

II 

V 

(! 

2) 

(integer-length!! 

(! 

4)) 

<=> 

(! 

3) 

(integer-length!! 

(! 

7)) 

<=> 

(! 

3) 

(integer-length!! 

( ! 

-D) 

<=> 

(! 

0) 

(integer-length!! 

(! 

-4)) 

A 

II 

V 

(! 

2) 

(integer-length!! 

(! 

-7)) 

<=> 

(! 

3) 

(integer-length!! 

(! 

-8)) 

<=> 

( ! 

3) 


Notes- 

References 
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integer-reverse!! [Function] 

Returns a pvar containing a bit-reversed copy of the values of the supplied integer 
pvar. 


Syntax- 

integer-reverse!! integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar containing values to be reversed. 


Returned Value- 

reversed-pvar Temporary integer pvar. In each active processor, contains a 
copy of the corresponding value of integer-pvar with the bits 
reversed, high-order exchanged with low-order and vice versa. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns an integer pvar of the same type and length as the argument. 
The result pvar contains a bit-reversed copy of integer-pvar 's bits, treated as an 
unsigned integer. The high-order bits become the low-order bits and vice versa. 
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Examples 


Notes- 

Usage Note: 

This function relies on the internal representation of pvars in the Connection 
Machine system and therefore cannot work in the *Lisp simulator. 

References- 
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integerp!! [, Function] 

Performs a parallel test for integer values on the supplied pvar. 

Syntax- 

integerp!! pvar 

Arguments- 

pvar Pvar expression. Pvar to be tested for integer values. 

Returned Value- 

integerp-pvar Temporary boolean pvar. Contains the value t in each proces¬ 
sor where pvar contains an integer value. Contains the value nil 
in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This is the parallel equivalent of the Common Lisp function integerp. 
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Examples 

Notes- 


References- 

See also these related pvar data type predicates: 

booleanp!! characterp!! complexp!! 

floatp!! front-end-p!! 

numberp!! string-char-p!! structurep!! 

typep!! 
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isqrt!! [Function] 

Calculates in parallel the square root of the supplied integer pvar. 

Syntax- 

isqrt!! integer-pvar 

Arguments- 

integer-pvar Integer pvar. Must contain only non-negative values. Pvar for 

which the square root is calculated. 

Returned Value- 

isqrt-pvar Integer pvar. In each active processor, contains the square root 

of the corresponding value of integer-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This is the parallel equivalent of the Common Lisp function isqrt. 
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Examples-— 

Notes- 

References- 
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Icm!! [Function] 

Computes in parallel the least common multiple of the supplied integer pvars. 


Syntax- 

Icm!! integer-pvar &rest integer-pvars 


Arguments- 

integer-pvar, integer-pvars 

Integer pvars. Pvars for which LCM is to be calculated. 


Returned Value- 

lem-pvar Temporary integer pvar. In each active processor, contains the 

least common multiple of the corresponding values of the integ¬ 
er-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function Icm!! takes one or more integer-pvars and computes, in each proces¬ 
sor, the least common multiple of the values of the integer-pvars in that processor. 
It always returns a non-negative integer pvar. Specifically: 

■ If one argument is given, its absolute value is returned in each processor. 

■ If two arguments are given, the Icm of the two pvar components is returned 
in each processor. 

■ If three or more arguments are given, the behavior is: 

(lem! ! a b c ... z) = (1cm! ! (1cm! ! a b) c ... z) 
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■ If one or more arguments (component values) are zero, then the result is 
zero. 

■ For two arguments that are not both zero, the behavior is: 

(lcm! ! a b) <=> 

(truncate!! (abs!! (*!! a b)) (gcd!! a b )) 

Examples- 

Notes- 

References- 


528 








*Lisp Dictionary 


Idb!! 


Idb!! [Function] 

Extracts a byte in parallel from the supplied pvars. 

Syntax- 

Idb!! bytespec-pvar integer-pvar 

Arguments- 

bytespec-pvar 
integer-pvar 

Returned Value 

byte-pvar Temporary integer pvar. In each active processor, contains a 

copy of the byte of integer-pvar specified by bytespec-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

The function Idb!! is similar to the function load-byte!! and is the parallel equiva¬ 
lent of the Common Lisp function Idb. The bytespec-pvar specifies a byte of integer- 
pvar to be extracted. The result is returned as a non-negative integer pvar. The fol¬ 
lowing forms are equivalent. 

(load-byte!! integer-pvar position-pvar size-pvar) 

<=> 

(Idb!! (byte!! size-pvar position-pvar) integer-pvar) 


Byte specifier pvar, as returned from byte!!. Determines posi¬ 
tion and size of byte in integer-pvar that is extracted. 

Integer pvar. Integer from which byte is extracted. 
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Examples 


Notes 


References 


See also these related byte manipulation operators: 


byte!! 

deposit-byte!! 
Idb—test!! 


byte-position!! 

deposit-field!! 

load-byte!! 


byte-size!! 
dpb!! 

mask-field!! 
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Idb-test!! [Function] 

Tests in parallel whether a specified byte is non-zero in the supplied integer pvar. 


Syntax- 

Idb-test!! bytespec-pvar integer-pvar 


Arguments- 

bytespec-pvar Byte specifier pvar, as returned from byte!!. Determines posi¬ 
tion and size of byte in integer-pvar which is tested. 

integer-pvar Integer pvar. Integer in which byte is tested. 

Returned Value- 

byte-test-pvar Temporary boolean pvar. Contains the value t in each active 
processor in which the byte of integer-pvar specified by 
bytespec-pvar is non-zero. Contains nil in all other active pro¬ 
cessors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is a predicate test and the parallel equivalent of Idb-test. It returns t 
in those processors where the byte field of integer-pvar specified by bytespec-pvar is 
non-zero. Elsewhere, it returns nil. 
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Examples 


Notes 


References 


See also these related byte manipulation operators: 
byte!! byte-position!! 

deposit-byte!! deposit-field!! 

Idb!! load-byte!! 


byte-size!! 
dpb!! 

mask-field!! 
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least-negative-float!! [Function] 

Returns a pvar containing the negative floating-point value that is closest to zero and 
representable in the format of the supplied floating-point pvar. 


Syntax- 

least-negative-float!! floating-point-pvar 


Arguments- 

floating-point-pvar 

Floating-point pvar. Determines format of returned pvar. 


Returned Value- 

least-neg-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the negative floating-point value closest to zero and 
representable in the same format as the corresponding value of 
floating-point-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a floating-point pvar with the same format (single or double 
precision) as the argument floating-point-pvar. In each processor, the returned 
value is the negative floating point number closest to (but not equal to) zero that 
can be represented by the CM in the same floating-point format as floating-point- 
pvar. 
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least-negative-f loat!! 


Examples-- 

The argument floating-point-pvar may be any floating point pvar of the required 
format. For example,' 

(least-negative-float!! (!! 0.0)) <=> (!! -1.1754944e-38) 

The same result would be obtained with an argument of (!! 5.8) or with any single¬ 
precision floating-point pvar. 

Notes- 


References- 

See also these related floating-point pvar limit functions: 

float-epsilon!! least-positive-float!! 

most-negative-float!! most-positive-float!! negative-float-epsilon!! 
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least-positive-float!! [Function] 

Returns a pvar containing the positive floating-point value that is closest to zero and 
representable in the format of the supplied floating-point pvar. 


Syntax- 

least-positive-float!! floating-point-pvar 


Arguments- 

floating-point-pvar 

Floating-point pvar. Determines format of returned pvar. 


Returned Value- 

least-pos-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the positive floating-point value closest to zero and 
representable in the same format as the corresponding value of 
floating-point-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a floating-point pvar with the same format (single or double 
precision) as the argument floating-point-pvar. In each processor, the returned 
value is the positive floating point number closest to (but not equal to) zero that can 
be represented by the CM in the same floating-point format as floating-point-pvar. 
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Examples- 

The argument floating-point-pvar may be any floating point pvar of the required 
format. For example, 

(least-positive-float!! (!! 0.0)) <=> (!! 1.1754944e-38) 

The same result would be obtained with an argument of (!! 5.8) or with any single¬ 
precision floating-point pvar. 

Notes- 


References- 

See also these related floating-point pvar limit functions: 

float-epsilon!! least-negative-float!! 

most-negative-float!! most-positive-float!! negative-float-epsilon!! 
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length!! [Function] 

Returns a pvar containing the lengths of the sequences in the supplied pvar. 

Syntax- 

length!! sequence-pvar 

Arguments- 

sequence-pvar Sequence pvar. Pvar containing sequences for which lengths 
are determined. 

Returned Value- 

length-pvar Temporary integer pvar. Contains in each active processor the 

length of the sequence in sequence-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a positive integer pvar containing in each processor the num¬ 
ber of elements in the corresponding sequence of sequence-pvar. 

The argument sequence-pvar must be a vector pvar. The pvar returned by length!! 
holds the same value in each processor. The following forms are equivalent: 

(length!! sequence-pvar) 

<=> 

(!! (*array-total-size sequence-pvar)) 
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Examples 


Notes- 

Compiler Note: 

The ’“Lisp compiler does not compile this operation. 


References- 

See also these related *Lisp sequence operators: 
copy-seq!! Mill 

‘nreverse reduce!! reverse!! 

subseq!! 

See also the generalized array mapping functions amap!! and *map. 


538 




*Lisp Dictionary 


*let 


*let [Macro] 

Allocate local pvars that exist only during the evaluation of a set of forms. 

Syntax- 

*iet ( &rest var-descriptors ) 

&optional declarations 
&body body 


Arguments- 

var-descriptors A series of local pvar descriptors. Each descriptor can be 
either a list of the form ( symbol pvar-expression ) to specify a 
local pvar with an initial value, or just symbol to specify a local 
pvar without an initial value. 

The var-descriptor components symbol and pvar-expression are described below. 
symbol Symbol to which the corresponding local pvar is bound. 

pvar-expression Pvar expression. Defines initial value of local pvar. 


declarations Optional type declaration forms. 

body *Lisp forms. Evaluated with the specified bindings in effect. 


Returned Value- 

last-form-value Returns value of last body form evaluated. May be either a pvar 

or a front-end value. If a local pvar is returned, it becomes a 
temporary pvar. 


Side Effects- 

Allocates the specified local pvars on the stack during the evaluation of the body 
forms. 
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Description- 

The ‘let macro is used to allocate local pvars that exist only during the evaluation 
of a series of *Lisp forms. 

The first argument of a call to * let must be a list containing any number of local 
pvar descriptors. Each descriptor can be a list consisting of a symbol that will name 
the local pvar, followed by a pvar-expression that will be used to initialize the pvar. 
Optionally, if no pvar-expression is required, the descriptor may be abbreviated to 
just the symbol. 

The following call to Met illustrates the two possible var-descriptor forms: 

(*let (no-init ;;; this local pvar is not initialized 

(inited (!! 0))) ;;; this pvar is initialized to (!! 0) 
(♦set no-init inited) 
no-init) => (!! 0) 

The *let macro expects its first argument to be a list of pvar descriptors; even if no 
local pvars are defined, an empty list must be provided as the first argument to Met. 

(•let () 

(*!! (self-address!!) (!! 5))) 

The declarations argument can be any number of *Lisp declaration forms. These 
forms can include, but are not limited to, type declarations for the local pvars 
defined by the variable descriptors of the Met. 

Local pvars survive only for the extent of the supplied body forms, but may be ac¬ 
cessed and modified by any functions these forms call. In other words, the symbols 
defined by the Met macro have lexical scope (as in Common Lisp), whereas the 
pvars themselves have dynamic extent that terminates when the Met form is exited. 

The Met macro returns the value of the last form of body. If a local pvar is returned 
as the value of the Met, it becomes a temporary pvar and its contents should be 
copied into another pvar. The Met macro is not able to return multiple values. 
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Examples- 

This * let example “rolls” a pair of dice in each processor and returns the maximum 
roll value obtained in all processors as a single front-end value. 

(*let ((diet (1+!! (random!! (!! 6)))) 

(die2 (1+!! (random!! (!! 6))))) 

(declare (type (field-pvar 8) diel die2)) 

(*max (+!! diel die2))) 

Here is a call to "let that defines only one local pvar. Note that the first argument to 
this Met call is still a list of lists. 

(*let ((local-pvar (!! 3))) 

(*!! local-pvar (!! 5))) 

The Met macro expects its first argument to be a list of local pvar descriptors. This 
expression would not work, for example, if it was mistakenly written as 

(*let (local-pvar (!! 3)) ;;; Error: Not a list of lists 

(*!! local-pvar (!! 5))) 

The Met macro is also able to allocate local pvars without initial values. In the fol¬ 
lowing example, the pvars x and y are not initialized by the Met operator. 

(*let (x 

y 

(scratch-pvar (!! 0))) 

(declare (type string-char-pvar x y)) 

(*set x (get-first-data-pvar)) 

(*set y (get-second-data-pvar)) 

(operate-on-pvars x y scratch-pvar)) 

The contents of uninitialized local pvars such are not defined until values have 
been stored into them by an operator such as *set, as in the above example. It is an 
error to attempt to reference the contents of an unintialized pvar before its values 
have been defined in this way. For example, the following expression is in error, and 
its returned value is not defined: 

(*let (x) 

(declare (type single-float-pvar x)) 

(pref x 0)) ;;; Error: value of x has not yet been defined 
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In general it is wise to declare the pvars allocated by *let. This allows the *Lisp 
compiler to compile expressions involving those pvars. Here is the die-rolling 
example with diel and die2 declared: 

(*let ((diet (1+!! (random!! (!! 6)))) 

(die2 (1+!! (random!! (!! 6))))) 

(declare (type (field-pvar 8) diel die2)) 

(*max (+!! diel die2))) 

The length of a local pvar allocated by *let may be determined at run time. 

For example: 

(*let ((processor-address (self-address!!))) 

(declare 

(type (field-pvar *current-send-address-length*) 
processor-address)) 


) 

This type of declaration insures that pvars are defined efficiently, with the exact 
bit-size that is required. 

A more complex type declaration example is provided by the following definition: 

(defun make-me-a-float (type) 

(let ((s (if (eq type :single) 23 52)) 

(e (if (eq type :single) 8 11))) 

(*let ((my-float (!! 0.0))) 

(declare (type (pvar (defined-float s e)) my-float)) 
my-float))) 

This function returns a floating point pvar of either single or double precision, 
depending on the value of its type argument. 

Array pvars can be allocated on the *Lisp stack by declaring them appropriately 
from within a *let or a *let* form. However, when allocating an array using ‘let or 
•let*, it is wise to explicitly declare the type of the pvar because undeclared pvars 
that have held any other type of data cannot hold arrays. 
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Here are some examples of the creation of local array pvars: 

(*let (foo) 

(declare (type (pvar (array single-float (3 3))) foo)) 
(*setf (aref!! foo (!! 0) (!! 1)) (!! 2.3)) 

(aref (pref foo 0) 0 1) 

) 


(*let ((bar (make-array!! '(333) 

:element-type '(pvar boolean) 

:initial-element t) 

)) 

(declare (type (pvar (array boolean (3 3 3))) bar)) 
(ppp bar rend 1) 

) 


=> 

#3A(((T T T)(T T T)(T T T)) 

( (T T T) (T T T) (T T T) ) 

( (T T T) (T T T) (T T T) ) ) 

It is possible to allocate array pvars whose dimensions are known only at run time. 
A properly constructed array pvar type declaration within a *let or a *let* form is 
used. The dimensions specification of the declaration may be given in one of two 
ways: 

■ A list of dimension values, (xy z), may be given, such that x, y, and z each 
evaluate to integers at run time. 

■ A variable may be named. Its value at run time must be a list of integers. 
For example: 

(defun make-2d-array-pvar (x y) 

(*let (temp-array) 

(declare (type (pvar (array single-float (x y))) 
temp-array)) 

temp-array)) 

Here, the formal parameters x and y are bound to specific values upon invocation 
of make-2d-array. The dimensions of temp-array are then determined upon exe¬ 
cution of the form. 


543 




•let 


*Lisp Dictionary 


Any array pvar declaration form expects a list of integers specifying array dimen¬ 
sions. Consider the following two function defintions: 

(defun good-make-array-pvar (input-scalar-array) 

(let ((dims (array-dimensions input-scalar-array))) 

(*let (temp) 

(declare (type (pvar (array single-float dims)) temp)) 
temp))) 


(defun bad-make-array-pvar (input-scalar-array) 

(*let (temp) 

(declare 

(type (pvar (array single-float 

(array-dimensions input-scalar-array))) 

temp)) 

temp)) 

The bad-make-array-pvar function definition is in error because it places the form 
(array-dimensions input-scalar-array) inside the declare form. The declaration 
should instead contain a list of integer dimensions or a symbol bound to such a list. 

The good-make-array-pvar function definition works properly because the 
symbol dims is bound to a list of integers, the result of evaluating 
(array-dimensions input-scalar-array), outside of the declare form. The symbol 
dims is then supplied to the declare form, which, when executed, finds dims 
properly bound to a list of integers. 


Notes 


References- 

See also the pvar allocation and deallocation operations 


allocate!! 

array!! 


•deallocate 

*deallocate-*defvars 

*defvar 

front-end!! 

•let* 


make-array!! 

typed-vector!! 

vector!! 


!! 

See also the *Lisp predicate allocated-pvar-p. 
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*let* [Macro] 

Allocates a set of local pvars that exist only during the evaluation of a set of forms. 


Syntax- 

•let* ( &rest var-descriptors ) 
declarations 
&body body 


Arguments- 

var-descriptors A series of local pvar descriptors. Each descriptor can be 
either a list of the form ( symbol pvar-expression ) to specify a 
local pvar with an initial value, or just symbol to specify a local 
pvar without an initial value. 

The var-descriptor components symbol and pvar-expression are described below. 
symbol Symbol to which the corresponding local pvar is bound. 

pvar-expression Pvar expression. Defines initial value of local pvar. 


declarations Optional type declaration forms. 

body *Lisp forms. Evaluated with the specified bindings in effect. 


Returned Value- 

last-form-value Returns value of last body form evaluated. 


Side Effects- 

Allocates the specified local pvars on the stack during the evaluation of the body 
forms. 
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Description- 

The *let* macro is used to allocate local pvars that exist only during the evaluation 
of a series of *Lisp forms. This macro behaves identically to *let except that, as in 
Common Lisp, variable descriptors are evaluated in sequence, so that the value 
bound to each variable can be used in defining the values of succeeding variables. 

The first argument of a call to * let* must be a list containing any number of local 
pvar descriptors. Each descriptor can be a list consisting of a symbol that will name 
the local pvar, followed by a pvar-expression that will be used to initialize the pvar. 
Optionally, if no pvar-expression is required, the descriptor may be abbreviated to 
just the symbol. As noted above, the pvar-expression of each local pvar descriptor 
can reference the values of all preceding local pvars defined by the *let* form. 

The declarations argument can be any number of *Lisp declaration forms. These 
forms can include, but are not limited to, type declarations for the local pvars 
defined by the variable descriptors of the *let*. 

The * let* macro returns the value of the last form of body. If a local pvar is returned 
as the value of the *let*, it becomes a temporary pvar and its contents should be 
copied into another pvar. The *let* macro is not able to return multiple values. 


Examples- 

This example “rolls” a pair of dice in each processor, and returns the maximum roll 
value obtained. Note that the value of the local pvar dice-roll depends on the values 
of the previously defined local pvars diel and die2. 

(*let ((diel (1+!! (random!! (!! 6)))) 

(die2 (1+!! (random!! (!! 6)))) 

(dice-roll (+!! diel die2))) 

(*max dice-roll)) 

See the definition of *let for more examples, including examples of local pvar type 
declaration. 
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•let* 


Notes 


References- 

See also the pvar allocation and deallocation operations 

allocate!! array!! 

•deallocate *deallocate-*defvars *defvar 

front-end!! *let 

make-array!! typed-vector!! vector!! 

!! 

See also the *Lisp predicate allocated-pvar-p. 
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let-vp-set [Function] 

Creates a temporary VP set that exists only during the evaluation of a set of forms. 

Syntax- 

let-vp-set ( vp-set-name vp-set-creation-form ) &body body 

Arguments- 

vp-set-name Symbol to which the temporary VP is bound. 
vp-set-creation-form 

VP set expression. Defines temporary VP set. 
body *Lisp forms. Evaluated with vp-set-name bound to the VP set. 

Returned Value- 

last-form-value Returns value of last body form evaluated. 

Side Effects- 

Allocates the specified VP set during the evaluation of the body forms, then deallo¬ 
cates it, using deallocate-vp-set. 


Description- 

This macro creates a temporary VP set that may be used only within the supplied 
body forms. The symbol vp-set-name is bound to the VP set object returned by 
vp-set-creation-form, which should be either a call to create-vp-set or a form that 
makes such a call. The body forms are then executed. Finally, deallocate-vp-set is 
called to deallocate vp-set-name and the form is exited. 

The returned value of let-vp-set is the value of the last form in body. 
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let-vp-set 


Examples 


(progn 

(let-vp-set (temp-cube (create-vp-set '(32 32 32))) 
(*with-vp-set temp-cube 
(♦let ((thoughts (!! 5)) 

(random (random!! (!! 10)))) 

(declare (type (field-pvar 8) thoughts random)) 

(*set thoughts (*!! random thoughts))))) 

(format t "Now the temp-cube vp-set no longer exists")) 

Notice that the temporary VP set created by a let-vp-set form must be explicitly 
selected with a *with-vp-set form before it is used. Notice also that the temp-cube 
VP set is deallocated upon exit of the let-vp-set. 


Notes 


References 


See also the following VP set definition and deallocation operators: 

def-vp-set create-vp-set 

deallocate-def-vp-sets deallocate-vp-set 


See also the following flexible VP set operators: 

allocate-vp-set-processors allocate-processors-for-vp-set 

deallocate-vp-set-processors deallocate-processors-for-vp-set 

set-vp-set-geometry with-processors-allocated-for-vp-set 

These operations are used to select the current VP set: 
set-vp-set *with-vp-set 


See also the following VP set information operations: 


dimension-size 

describe-vp-set 

vp-set-dimensions 

vp-set-total-size 


dimension-address-length 

vp-set-deallocated-p 

vp-set-rank 

vp-set-vp-ratio 
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*light [ * Defun] 

Sets the pattern displayed on the front panel LED’s. 

Syntax- 

*light boolean-pvar 


Arguments- 

boolean-pvar Boolean pvar. Determines pattern displayed on front panel 
LED’s. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Sets front panel LED’s based on the value of the supplied boolean-pvar. 


Description- 

This function provides control of the patterns displayed on the front-panel LED’s. 

Each LED is connected to sixteen processors with sequential send addresses. The 
•light function affects only those LED’s for which all sixteen processors are se¬ 
lected. Each LED is turned on if all of its corresponding sixteen processors contain 
the value nil in boolean-pvar, and turned off if any processor is non-nil. The state 
(lit/unlit) of the remaining (unselected) LED’s is unchanged. 
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Examples 


Notes- 

Usage Note: 

Before using the * light function, it is necessary to call the Paris function 
CM:set-system-leds-mode with an argument of nil to disconnect the LED’s 
from their normal processor monitoring mode, in which each LED is turned on 
whenever any of the sixteen processors to which that LED is connected are 
active. 


References 
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•lisp 


*lisp [Function] 

Switches between user and ‘lisp packages. 

Syntax- 

•lisp &optional select-*lisp 

Arguments- 

select-*lisp Boolean value or the keyword :toggle. If supplied, determines 

which package is selected. If not, defaults to : toggle. 

Returned Value- 

None. Returns no values. 


Side Effects- 

Changes the value of 'package*. 


Description- 

The function *lisp makes switching the current package from user to *lisp and 
back again easy. It should be called only at top level. The select-*lisp argument 
determines which package is selected. A value of t sets the current package to *lisp. 
A value of nil sets the current package to user. The keyword :toggle, the default, 
toggles between the user and *lisp packages. 
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Examples- 

Called with an argument of :toggle, the default, the function *lisp toggles the cur¬ 
rent package between the user and *lisp packages: 

(in-package 'user) 

(*lisp :toggle) 

Default package is now ♦LISP. 

(♦lisp) ;;; :toggle is the default 
Default package is now USER. 


An argument of t forces selection of the *li$p package, and an argument of nil 
forces selection of the user package: 


(in-package 'user) 


(♦lisp t) 

Default package is now *LISP. 


(♦lisp t) 
Default package 


is now *LISP. 


(♦lisp nil) 

Default package is now USER. 


(♦lisp nil) 

Default package is now USER. 


Notes 


References 
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list-of-active-processors [Function] 

Returns list containing the send addresses of all active processors. 

Syntax- 

list-of-active-processors 


Arguments- 

Takes no arguments. 

Returned Value- 

send-address-list List of integers. Send addresses of all active processors. 

Side Effects- 

None. 


Description- 

This simply returns a list of the send addresses of all the currently selected proces¬ 
sors. The order of this list is not specified. This function could be written as: 

(defun my-list-of-active-processors () 

(let ((return-list nil)) 

(do-for-selected-processors (processor) 

(push processor return-list)) 

(nreverse return-list))) 
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Examples 


Notes 


References- 

See also the definition of loap, a predefined alias for list-of-active-processors, 
and the looping operator do-for-selected-processors. 

See also the related processor selection operators 


‘all 


‘if 

if!! 

*case 

case!! 

*cond 

cond!! 

*ecase 

ecase! 

‘unless 

‘when 


with-css-saved 
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load-byte! ! [Function] 

Extracts a byte in parallel from the supplied integer pvar. 

Syntax- 

load-byte!! integer-pvar position-pvar size-pvar 

Arguments- 

integer-pvar 
position-pvar 

size-pvar 

Returned Value 

byte-pvar Temporary integer pvar. In each active processor, contains the 

byte of integer-pvar specified by position-pvar and size-pvar. 


Integer pvar. Pvar from which byte is extracted. 

Integer pvar. Bit position, zero-based, of byte of integer-pvar to 
extract. 

Integer pvar. Bit size of byte to extract. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function load-byte! ! extracts a byte in parallel from the supplied integer-pvar. 

In each processor, this function extracts a byte from the value of integer-pvar, of 
size in bits specified by size-pvar and starting at the position specified by position- 
pvar (position 0 corresponds to the least significant bit). The following forms are 
equivalent: 

(load-byte!! integer-pvar position-pvar size-pvar) 

<=> 

(ldb!! (byte!! size-pvar position-pvar) integer-pvar) 
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Examples--- 

In any processor in which zero bits are extracted, the resulting field contains zero. 
Out-of-range bits are treated as zero for positive integers, and one for negative in¬ 
tegers. For example, 

(load-byte!! (!! 1) (!! 2) (!! 3)) <=> (!! 0) 

(load-byte!! (!! -1) (!! 2) (!! 3)) <=> (!! 7) 


Notes- 

Usage Note: 

This operation is especially fast when both position-pvar and size-pvar are con¬ 
stants, as in 

(load-byte!! data-pvar (!! 2) (!! 3)) 


References- 

See also these related byte manipulation operators: 

byte!! byte-position!! byte-size!! 

deposit-byte!! deposit-field!! dpb!! 

Idb!! Idb—test!! mask-field!! 
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loap [Function] 

Returns list containing the send addresses of all active processors. 

Syntax- 

loap 

Arguments- 

Takes no arguments. 

Returned Value- 

retumed-value Returned value. 

Side Effects- 

None. 

Description- 

This function is an alias for list-of-active-processors. 
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Examples - 

Notes- 

References 
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*IOCally [Macro] 

Provides the *Lisp compiler with declarations that remain in effect for the duration of 
a body form. 

Syntax- 

‘locally declaration-1 declaration-2 ... declaration-n &body body 

Arguments- 

declaration-n Declaration forms. 

body *Lisp forms. Compiled with the specified declarations in ef¬ 

fect. 


Returned Value- 

last-form-value Returns value of last body form evaluated. 

Side Effects- 

None. 


Description- 

This macro is used to provide declarations for the *Lisp compiler. The declara¬ 
tions declaration-1 through declaration-n are used by the compiler for the body of 
the body form. A ‘locally declaration must be a declare form. Any valid composi¬ 
tions of declare may be used within a ‘locally form, including optimize and 
‘optimize forms. 

The *Lisp compiler’s code walker largely eliminates any need to use the ‘locally 
operator. See Chapter 4, “*Lisp Type Declaration,” for a description of this feature 
and of other operators that should be used instead of ‘locally. 
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Examples- 

A simple example of the use of ‘locally is 

(setq allocated-pvar 

(allocate!! (!! 0.0) nil 'single-float-pvar)) 

(♦locally 

(declare (type single-float-pvar allocated-pvar)) 

(♦let (result-pvar) 

(♦set allocated-pvar (random!! (!! 10.0)))) 

(dotimes (i 3) 

(♦incf result-pvar allocated-pvar))) 

in which allocated-pvar is declared to be of type single-float-pvar. 

An example of the use of * locally in a function definition is 

(defun ♦locally-test (j) 

(♦locally 

(declare (type fixnum j)) 

(♦let (temp) 

(declare (type (unsigned-byte-pvar 32) temp)) 

(♦set temp (!! j)) 

(ppp temp :end 8)))) 

The use of * locally in this function declares the type of the scalar argument j, allow¬ 
ing this function to execute more efficiently in both interpreted and compiled form. 

(♦locally-test 1.0) 

1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 

The following example displays many of the locations in which * locally can be used 
to provide a localized declaration. 

(♦cold-boot :initial-dimensions '(8 4)) 

(♦proclaim '(type single-float-pvar result-pvar)) 

(♦defvar result-pvar) 


562 





*Lisp Dictionary 


^locally 


(defun ♦locally-example (result) 

(♦locally 

(declare (type single-float-pvar result)) 
(do-for-selected-processors (j) 

(♦locally 

(declare (type fixnum j)) 

(f let 

((local-pvar-function (x) 

(♦locally 

(declare (type single-float-pvar x result)) 
(declare (*optimize (safety 0))) 

(♦set result (+!! x (!! j))) 

))) 

(dotimes (i *number-of-processors-limit*) 

(♦locally 

(declare (type fixnum i)) 

(♦let ((temp (*!! (+!! (float!! (!! i)) (!! j)) 

(sin!! (!! j))))) 

(declare (type single-float-pvar temp)) 
(local-pvar-function temp) 

)))))))) 

(♦locally-example result-pvar) 

(ppp result-pvar rend 6) 

5.94665 5.94665 5.94665 5.94665 5.94665 5.94665 


Notes 


References- 

See also the related *Lisp declaration operators: 

•proclaim unproclaim 

See also the related type translation function taken-as!!. 
See also the related type coercion function coerce!!. 
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log!! [Function] 

Takes the logarithm of the supplied pvar. 


Syntax- 

log!! numeric-pvar &optional base-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which logarithm is calculated. 

base-pvar Numeric pvar. If supplied, determines base in which logarithm 

is calculated. Defaults to base of natural logarithms. 


Returned Value- 

log-pvar Numeric pvar. In each active processor, contains logarithm of 

the corresponding value of numeric-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns the logarithm of the argument numeric-pvar in the base 
base-pvar. If base-pvar is absent, the natural logarithm is returned. 

The argument numeric-pvar must be either a non-negative floating-point pvar or a 
non-negative integer pvar. The argument base must be a positive, non-complex 
number pvar. 
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Examples- 

(log!! (!! 4) (!! 2)) <=> (!! 2.0) 


Notes- 

The function log!! will never return a complex pvar as its result unless 
numeric-pvar is complex, or is coerced into complex form by use of the functions 
complex!! or coerce!!, as shown below. 

(log!! (coerce!! (!! -1) '(pvar (complex single-float)))) 

<=> 

(log!! (complex!! (!! -1.0))) 

<=> 

(!! #c(0.0 3.1415927)) 


References 
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* logand [* Defun] 

Returns bitwise logical AND of all values in the supplied integer pvar. 

Syntax- 

* logand integer-pvar 

Arguments- 

integer-pvar Integer pvar. Pvar for which logical AND is calculated. 

Returned Value- 

logand-integer Integer. Bitwise logical AND of all values in integer-pvar. 

Side Effects- 

None. 

Description- 

This returns a Lisp value that is the bitwise logical AND of the contents of 
integer-pvar in all selected processors. This returns the Lisp value -1 if there are no 
selected processors. 
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Examples- 

(♦logand (!! 7)) => 7 

(♦when nil!! (*logand (!! 7))) => -1 

(♦logand (if!! (evenp!! (self-address!!)) 
(! ! 6 ) 

(M3))) => 2 

(♦logand (!! 0)) => 0 


Notes 


References- 

See also the related global operators: 


and 

•integer-length 


logior 

•logxor 

•max 

min 

*or 

•sum 

xor 




See also the related logical operators: 

and!! not!! or!! xor!! 
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logand!! [Function] 

Performs a parallel bit-wise logical AND operation on the supplied integer pvars. 


Syntax- 

logand!! &rest integer-pvars 


Arguments- 

integer-pvars Integer pvars. Combined using bit-wise logical AND. 


Returned Value- 

logand-pvar Temporary integer pvar. In each active processor, contains the 
bit-wise logical AND of the corresponding values of the integ¬ 
er-pvars. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This returns a pvar whose bits are the logical AND of the bits in integer-pvars. If no 
integer-pvars are given, then (!! -t) is returned. 
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Examples- 

(logand!! (!! 7) (!! 7)) <=> (!! 7) 

(logand!! (!! 7) (!! 3)) <=> (!! 3) 

(logand!! (!! 7) (!! 6) (!! 3)) <=> (!! 2) 

(logand!! (!! 7) (!! 0)) <=> (!! 0) 


Notes 


References 
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logandcl!! [Function] 

Performs a parallel bit-wise logical AND operation on the supplied integer pvars, after 
taking the ones complement of its first argument. 


Syntax- 

logandcl!! integer-pvarl integer-pvar2 


Arguments- 

integer-pvarl Integer pvar. Complemented, then combined with 
integer-pvar2 using bit-wise logical AND. 

integer-pvar2 Integer pvar. Combined with ones complement of integer- 
pvarl using bit-wise logical AND. 

Returned Value- 

logandcl-pvar Temporary integer pvar. In each active processor, contains the 

result of combining the ones complement of integer-pvarl with 
integer-pvar2 using bit-wise logical AND. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes two integer pvars and, within each processor, performs a bit¬ 
wise logical AND operation on the supplied pvars, after taking the ones 
complement of its first argument. 

(logandcl!! pvarl pvar2) <=> (logand!! (lognot!! pvarl) pvar2) 
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Examples 

Notes- 


References 
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logandc2!! [ Function] 

Performs a parallel bit-wise logical AND operation on the supplied integer pvars, after 
taking the ones complement of its second argument. 


Syntax- 

logandc2!! integer-pvarl integer-pvar2 


Arguments- 

integer-pvarl Integer pvar. Combined with ones complement of integer- 
pvarl using bit-wise logical AND. 

integer-pvar2 Integer pvar. Complemented, then combined with integer- 
pvarl using bit-wise logical AND. 

Returned Value- 

logandc2-pvar Temporary integer pvar. In each active processor, contains the 

result of combining integer-pvarl with the ones complement of 
integer-pvar2 using bit-wise logical AND. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes two integer pvars and, within each processor, performs a bit¬ 
wise logical AND operation on the supplied pvars, after taking the ones comple¬ 
ment of its second argument. 

(logandc2!! pvarl pvar2) <=> (logand!! pvarl (lognot!! pvar2)) 
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Examples - 

Notes- 

References 
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logbitp!! [Function] 

Tests in parallel whether a specified bit of the supplied integer pvar is set. 


Syntax- 

logbitp!! index-pvar integer-pvar 


Arguments — 

index-pvar 

integer-pvar 


Integer pvar. Index, zero-based, of bit to be tested. 
Integer pvar. Pvar on which parallel bit test is performed. 


Returned Value- 

logbitp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the bit in integer-pvar specified by index-pvar 
is set (equal to 1). Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This predicate function tests in parallel whether a specified bit of the supplied inte¬ 
ger pvar is set. In each processor, logbitp! ! examines the bit specified by index-pvar 
in the value of integer-pvar, where 0 specifies the least significant bit. The returned 
pvar has the value t wherever the selected bit is a one-bit; otherwise it has the value 

nil. 


(logbitp!! index-pvar byte-pvar) 

<=> 

(plusp!! (1db!! (byte!! index-pvar (!! 1)) byte-pvar)) 
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Examples - 

Notes- 

References 
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logcount!! [Function] 

Determines in parallel the number of set bits in an integer pvar. 


Syntax- 

logcount!! inieger-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar in which set bits are counted. 


Returned Value- 

bitcount-pvar Integer pvar. In each active processor, contains the number of 
set bits in the corresponding value of integer-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function determines, in each processor, the number of one-bits in that proces¬ 
sor’s value of integer-pvar and returns a non-negative integer pvar containing the 
result. If the component of integer-pvar is positive, then the one-bits in its binary 
representation are counted. If the component of integer-pvar is negative, then the 
zero-bits in its two’s-complement binary representation are counted. 
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Examples- 

(ppp (logcount!! (self-address!!))) => 

0112122312232334. . . 

(logcount!! (!! 7)) <=> (!! 3) 

Notes- 


References 









*Lisp Dictionary 


logeqv!! 


logeqv!! [Function] 

Performs a parallel bit-wise logical equivalence operation on the supplied integer 
pvars. 


Syntax- 

logeqv!! &rest integer-pvars 


Arguments- 

integer-pvars Integer pvars. Combined using bit-wise logical equivalence. 


Returned Value- 

logeqv-pvar Temporary integer pvar. In each active processor, contains the 

result of performing a bit-wise logical equivalence operation 
on the corresponding values of the integer-pvars. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function logeqv. If no integer- 
pvars are given, then (!! -1) is returned. 
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Examples- 

(logeqv!! (!! 7) (!! 7)) <=> (!! -1) 

(logeqv!! (!! 7) (!! 3)) <=> (!! -5) 

(logeqv!! (!! 7) (!! 6) (!! 3)) <=> (!! 2) 

(logeqv!! (!! 7) (!! 0)) <=> (!! -8) 


Notes 


References 
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*logior [* Defun] 

Returns bitwise logical inclusive OR of all values in the supplied integer pvar. 

Syntax- 

•logior integer-pvar 

Arguments- 

integer-pvar Integer pvar. Pvar for which logical inclusive OR is calculated. 

Returned Value-- 

logior-integer Integer. Bitwise logical inclusive OR of all values in integer- 
pvar. 


Side Effects 

None. 


Description- 

This returns a Lisp value that is the bitwise logical inclusive OR of the contents of 
integer-pvar in all selected processors. This returns the Lisp value 0 if there are no 
selected processors. 
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Examples -- 

(*logior (!! 7)) => 7 
(♦when nil!! (*logior (!! 7))) => 0 

(♦logior (if!! (evenp!! (self-address!!)) 
(!! 6 ) 

(M3))) => 7 

(♦logior (!! 0)) => 0 


Notes 


References- 

See also the related global operators: 


and 

*integer-length 

*logand 

logxor 

*max 


min 

*or 

*sum 

xor 




See also the related logical operators: 

and!! not!! or!! xor!! 
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logior!! [Function] 

Performs a parallel bit-wise logical inclusive OR operation on the supplied integer 
pvars. 


Syntax- 

logior!! &rest integer-pvars 


Arguments- 

integer-pvars Integer pvars. Combined using bit-wise logical inclusive OR. 


Returned Value- 

logior-pvar Temporary integer pvar. In each active processor, contains the 

bit-wise logical inclusive OR of the corresponding values of the 
integer-pvars. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This returns a pvar whose bits are the logical inclusive OR of the bits in integer- 
pvars. If there are no integer-pvars, then (!! 0) is returned. 
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Examples- 

(logior! ! (! ! 0)) <=> (MO) 

(logior!! (!! 7) (!! 7)) <=> (!! 7) 

(logior!! (!! 7) (!! 3)) <=> (!! 7) 

(logior!! (!! 4) (!! 1) (!! 0)) <=> (!! 5) 

Notes- 

References- 
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lognand!! [ Function ] 

Performs a parallel bit-wise logical NAND operation on the supplied integer pvars. 


Syntax- 

lognand!! integer-pvarl integer-pvar2 


Arguments- 

integer-pvarl, integer-pvar2 

Integer pvars. Combined using bit-wise logical NAND. 


Returned Value- 

lognand-pvar Temporary integer pvar. In each active processor, contains the 
bit-wise logical NAND of the corresponding values of the integ- 
er-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes two integer pvars and, within each processor, performs a bit¬ 
wise logical NAND operation on the supplied pvars. The following forms are equiv¬ 
alent: 

(lognand!! pvarl pvar2) <=> (lognot!! (logand!! pvarl pvar2)) 
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Examples - 

Notes- 

References 
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lognor!! [ Function] 

Performs a parallel bit-wise logical NOR operation on the supplied integer pvars. 


Syntax- 

lognor!! integer-pvarl integer-pvar2 


Arguments- 

integer-pvarl, integer-pvar2 

Integer pvars. Combined using bit-wise logical NOR. 


Returned Value- 

lognor-pvar Temporary integer pvar. In each active processor, contains the 

bit-wise logical NOR of the corresponding values of the integ- 
er-pvars. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes two integer pvars and, within each processor, performs a bit¬ 
wise logical NOR operation on the supplied pvars. The following forms are equiva¬ 
lent: 


(lognor!! pvarl pvar2) 


<=> (lognot!! 


(logior!! pvarl pvar2)) 
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Examples- 

Notes- 

References- 
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lognot!! [Function] 

Returns the bitwise complement of the supplied integer pvar. 


Syntax- 

lognot!! integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar to be bitwise complemented. 


Returned Value- 

lognot-pvar Temporary integer pvar. In each active processor, contains the 

bit-wise complement of the corresponding value of integer- 
pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This returns a pvar whose values are the logical complement of the values in 
integer-pvar. 
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Examples - 

Notes- 

References 
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logorcl!! [Function] 

Performs a parallel bit-wise logical inclusive OR operation on the supplied integer 
pvars, after taking the complement of its first argument. 


Syntax- 

logorcl!! integer-pvarl integer-pvar2 


Arguments- 

integer-pvarl Integer pvar. Complemented, then combined with integer- 
pvarl using bit-wise logical OR. 

integer-pvar2 Integer pvar. Combined with integer-pvarl using bit-wise log¬ 
ical OR. 


Returned Value- 

logorcl-pvar Temporary integer pvar. In each active processor, contains the 

result of combining the complement of integer-pvarl with in- 
teger-pvar2 using bit-wise logical OR. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes two integer pvars and, within each processor, performs a bit¬ 
wise logical inclusive OR operation on the supplied pvars, after taking the comple¬ 
ment of its first argument. The following forms are equivalent: 

(logorcl!! pvarl pvar2) <=> (logior!! (lognot!! pvarl) pvar2) 
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Examples- 

Notes- 

References- 
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logorc2M 


logorc2!! [Function] 

Performs a parallel bit-wise logical inclusive OR operation on the supplied integer 
pvars, after taking the complement of its second argument. 


Syntax- 

logorc2!! integer-pvarl integer-pvar2 


Arguments- 

integer-pvarl Integer pvar. Combined with integer-pvar2 using bit-wise log¬ 
ical OR. 

integer-pvar2 Integer pvar. Complemented, then combined with integer- 
pvarl using bit-wise logical OR. 

Returned Value- 

logorc2-pvar Temporary integer pvar. In each active processor, contains the 
result of combining integer-pvarl with the complement of in- 
teger-pvar2 using bit-wise logical OR. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes two integer pvars and, within each processor, performs a bit¬ 
wise logical inclusive OR operation on the supplied pvars, after taking the comple¬ 
ment of its second argument. The following forms are equivalent: 

(logorc2M pvarl pvar2) <=> (logior!! pvarl (lognot!! pvar2)) 
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Examples 

Notes- 


References 
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logtest!! [Function] 

Performs a parallel test on the supplied integer pvars for bits which are set in both 
pvars. 


Syntax- 

logtest!! integer-pvarl integer-pvar2 


Arguments- 

integer-pvarl, integer-pvar2 

Integer pvars. Tested in parallel for bits set in both pvars. 


Returned Value- 

logtest-pvar Temporary boolean pvar. Contains the value t in each active 

processor where the values of integer-pvarl and integer-pvar2 
contain corresponding bits that are set in both pvars. Contains 
nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This predicate function is true in each processor where any of the one-bits in 
integer-pvarl is also a one-bit in integer-pvar2. The behavior is: 

(logtest!! pvarl pvar2) 

<=> 

(not!! (zerop!! (logand!! pvarl pvar2))) 
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Examples - 

Notes- 

References 
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*logxor [* Defun] 

Returns bitwise logical XOR of all values in the supplied integer pvar. 


Syntax- 

•logxor &rest integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar for which logical inclusive XOR is calcu¬ 

lated. 


Returned Value- 

logwr-integer Integer. Bitwise logical inclusive XOR of all values in 
integer-pvar. 


Side Effects 

None. 


Description- 

This returns a Lisp value that is the bitwise logical exclusive OR of the contents of 
integer-pvar in all selected processors. This returns the Lisp value 0 if there are no 
selected processors. 
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Examples- 

(*let ((test (!! 0))) 

(*setf (pref test 0) 1) 

(*setf (pref test 1) 2) 

(*setf (pref test 2) 4) 

(♦logxor test)) 

=> 7 


Notes 


References- 

See also the related global operators: 


*and 

•integer-length 

•logand 

•logior 

*max 


•min 

*or 

•sum 

*xor 




See also the related logical operators: 

and!! not!! or!! xor!! 
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logxor!! 


logxor!! [Function] 

Performs a parallel bit-wise logical XOR operation on the supplied integer pvars. 


Syntax- 

logxor!! &rest integer-pvars 


Arguments- 

integer-pvars Integer pvars. Combined using bit-wise logical XOR. 


Returned Value- 

logior-pvar Temporary integer pvar. In each active processor, contains the 

bit-wise logical XOR of the corresponding values of the integ¬ 
er-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function logxor. If there are no 
integer-pvars, then (!! 0) is returned. 
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Examples- 

(logxor!! (!! 7) (!! 7)) <=> (!! 0) 

(logxor!! (!! 1) (!! 3) (!! 4)) <=> (!! 6) 
(logxor!! (!! 0) (!! 1) (!! 2) (!! 4)) <=> (!! 7) 


Notes 


References 


600 




*Lisp Dictionary 


lower-case-p!! 


lower-case-p!! [Function] 

Performs a parallel test for lower-case characters on the supplied pvar. 


Syntax- 

lower-case-p!! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for lower-case characters. 


Returned Value- 

lowercasep-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is a 
lower-case alphabetic character. Contains nil in all other pro¬ 
cessors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This predicate returns a pvar that has the value t in each processor where the 
supplied character-pvar contains a lower-case character, and the value nil in all 
other processors. 
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Examples - 

Notes- 

References 
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make-array!! [Function] 

Creates and returns an array pvar. 


Syntax- 

make-array!! dimensions &key :element-type :initial-element 


Arguments- 

dimensions Integer, or list of integers. Dimensions of array pvar. 

: element-type Common Lisp or *Lisp type specifier. Specifies data type of 

elements, and must be supplied. 

: initial-element Scalar or pvar value. If supplied, determines initial value of 
array elements. 

Returned Value- 

array-pvar Temporary array pvar with the specified dimensions. Data type 

and initial contents are as specified by the : element-type and 
:initial-element arguments. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function make-array!! returns an array pvar on the *Lisp stack. 

The dimensions argument is either a single non-negative integer or a list of non¬ 
negative integers. Each integer must be less than *array-dimension-limit. If a list 
of dimensions is given, the length of the list must be less than ‘array-rank-limit. 
The product of all dimensions must be smaller than ‘array-total-size-limit. 
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Any valid fixed-size Common Lisp type or pvar type of fixed size may be specified 
as the value of : element-type. It is an error to not provide an : element-type 
argument when calling make-array!!. 

The value of: initial-element may be either a front-end scalar or a pvar. If it is a 
scalar, the function !! is used to convert it to a constant pvar. In either case, make- 
array! ! stores the value of initial-element in each processor into each element of the 
corresponding array. If initial-element is not specified, the contents of the newly 
created array are undefined. 

Unlike its Common Lisp counterpart, make-array! ! does not support the following 
keyword parameters: : initial-contents, :adjustable, :fill—pointer, :displaced-to, 
and :displaced-index-offset. 


Examples- 

(*defvar new-array-pvar) 

(*set new-array-pvar 

(make-array!! ' (2 2 2) 

:element-type '(complex single-float) 

:initial-element #c(5.3 0.0))) 

(aref (pref new-array-pvar 0) 0 1 0) => #C(5.3 0.0) 

A pvar consisting of a three-dimensional array containing single-precision com¬ 
plex numbers in each processor is defined and bound to the symbol new-array- 
pvar. The value (!! 5.3) is *set into new-array-pvar so that, in all active processors, 
each array element is initialized. An arbitrary array reference in processor 0 veri¬ 
fies the presence of an initial pvar array element value. 


Notes 


References 


See also the pvar allocation and deallocation operations 

allocate!! array!! 

'deallocate 'deallocate-'defvars 'defvar 

front-end!! 'let 'let* 

typed-vector!! vector!! !! 
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make-char!! 


make-char! ! [Function] 

Creates and returns a copy of a character pvar with modified bits and font attributes. 


Syntax- 

make-char!! character-pvar &optional bits-pvar forit-pvar 


Arguments- 

character-pvar Character pvar. Determines code attribute of returned charac¬ 
ter pvar. 

bits-pvar Integer pvar. If supplied, determines bits attribute of returned 

character pvar. Defaults to (!! 0). 

font-pvar Integer pvar. If supplied, determines font attribute of returned 

character pvar. Defaults to (!! 0). 


Returned Value- 

char-pvar Character pvar. In each active processor, contains a copy of the 

corresponding value of character-pvar, with bits and font at¬ 
tributes as specified by bits-pvar and font-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function attempts to construct a character pvar with the same code attribute 
as character-pvar and with the bits and font attributes specified by the optional 
bits-pvar and font-pvar arguments. In processors where this can be done, the re¬ 
sulting character is returned. In processors where this can not be done, nil is re¬ 
turned. 
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Examples 


Notes 


References- 

See also the related character pvar constructor character!!. 

See also the related character pvar attribute operators: 

char-bit!! char-bits!! char-code!! 

char-font!! initialize-character set-char-bit!! 
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*map [Function] 

Maps a function in parallel over the supplied array pvars. 

Syntax- 

•map operator &rest array-pvars 


Arguments- 

operator Symbol or functional object. Function to be applied. 

array-pvars Array pvars. Pvars containing arrays that function is mapped 

over. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

None other than those of the supplied function. 


Description- 

The *map function maps the supplied operator over the supplied array pvars. The 
operator is applied in turn to each set of elements having the same row-major index 
in the supplied array-pvars. Thus, the nth time function is called, it is applied to a 
list containing the nth element in row-major order from each of the array-pvars. 

The *Lisp function *map is similar to the Common Lisp function map, but while 
map works only on vectors, *map works on any type of array pvar. 

For vectors, *map behaves much like map in accepting vector pvar arguments of 
different element sizes and in limiting the mapping operation to the length of the 
shortest vector pvar supplied. For all other types of array pvars, however, *map 
expects the array sizes of the supplied array-pvars to be identical. 
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Examples- 

Suppose we have two matrices and we wish to add the two matrices together ele¬ 
ment by element, multiplying the result of the addition by a constant, and storing 
the overall result back in the first matrix. This can be accomplished by 

(♦proclaim '(type (pvar (array single-float (3 3))) 
matrixl matrix2)) 

(*defvar matrixl 

(!! #2A((1.0 2.0 3.0) (4.0 5.0 6.0) (7.0 8.0 9.0)))) 

(*defvar matrix2 

(!! #2A((3.0 2.0 1.0) (6.0 5.0 4.0) (9.0 8.0 7.0)))) 

(defun ♦map-example (single-float-constant) 

(declare (type single-float single-float-constant)) 

(♦map 

#'(lambda (elementl element2) 

(declare (type single-float-pvar elementl element2)) 
(♦set elementl (*!! (+!! elementl element2) 

(!! single-float-constant)))) 

matrixl 

matrix2 

)) 

(♦map-example 2.0) 

(pref matrixl 0) 

=> #2A((8.0 8.0 8.0) (20.0 20.0 20.0) (32.0 32.0 32.0)) 


Notes 


References- 

See also the related function amap!!. 
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mask-field!! [Function] 

Copies a bit field in parallel from the supplied integer pvar. 


Syntax- 

mask-field!! bytespec-pvar integer-pvar 


Arguments- 

bytespec-pvar Byte specifier pvar, as returned from byte! !. Determines posi¬ 
tion and size of bit field in integer-pvar which is copied. 

integer-pvar Integer pvar. Integer from which bit field is copied. 

Returned Value- 

newbyte-pvar Temporary integer pvar. In each active processor, contains an 
integer that agrees with the corresponding value of integer-pvar 
in the bit field specified by bytespec-pvar, and has zero bits 
elsewhere. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function mask-field!! is the parallel equivalent of the Common Lisp function 
mask-field. It is similar to Idb!!; however, the result contains, for each processor, 
the byte of integer-pvar that is in the position specified by bytespec-pvar, rather 
than in position 0 as with Idb!!. The newbyte-pvar result therefore agrees with 
integer-pvar in the byte specified, but has zero bits everywhere else. 
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mask-field!! 


The following forms are equivalent: 

(mask-field (byte!! size-pvar pos-pvar) bits-pvar) 

<=> 

(logand!! bits-pvar 

(dbp!! (!! -1) (byte!! size-pvar pos-pvar) 0)) 


Examples 


Notes 


References 


See also these related byte manipulation operators: 

byte!! byte-position!! 

deposit-byte!! deposit-field!! 

Idb!! Idb—test!! 


byte-size!! 
dpb!! 

load-byte!! 
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*max [* Defun] 

Returns the maximum numeric value contained in the supplied pvar. 

Syntax- 

•max numeric-pvar 

Arguments- 

numeric-pvar Numeric pvar. Pvar for which maximum value is determined. 

Returned Value- 

max-value Scalar value. Maximum numeric value contained in the numer¬ 

ic-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This returns a scalar value that is the maximum of the contents of numeric-pvar in 
all selected processors. This returns the Lisp value nil if there are no selected proc¬ 
essors. 
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Examples- 

(*max (mod!! (self-address!!) (!! 5))) <=> 4 


Notes 


References- 

See also the related global operators: 


and 

* integer-length 

*logand 

logior 

*logxor 


min 

*or 

*sum 

xor 
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max!! 


max!! [ Function ] 

Determines in parallel the maximum numeric value of the supplied pvars. 


Syntax- 

max!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar, numeric-pvars 

Numeric pvars. Pvars for which the maximum value is deter¬ 
mined. 


Returned Value- 

max-pvar Temporary numeric pvar. In each active processor, contains 

the maximum of the corresponding values of the supplied num¬ 
eric-pvar arguments. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This returns a pvar that contains in each processor the maximum of the 
corresponding values of the supplied numeric-pvars in that processor. 
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Examples- 

(PPP (max!! (mod!! (self-address!!) (!! 2)) 

(mod!! (self-address!!) (!! 3)))) => 
012112012112012 . . . 

Notes- 

References- 
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*min [ * Defun] 

Returns the minimum numeric value contained in the supplied pvar. 


Syntax- 

*min numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which minimum value is determined. 

Returned Value- 

min-value Scalar value. Minimum numeric value contained in the numer¬ 

ic-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This returns a scalar value that is the minimum of the contents of numeric-pvar in 
all selected processors. It returns the Lisp value nil if there are no selected proces¬ 
sors. 
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Examples- 

(*min (mod!! (self-address!!) (!! 5))) <=> 0 


Notes 


References 


See also the related global operators: 


*and 

•integer-length 

•logand 

•logior 

•logxor 

•max 

*or 

•sum 

*xor 
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min!! [ Function] 

Determines in parallel the minimum numeric value of the supplied pvars. 


Syntax- 

min!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar, numeric-pvars 

Numeric pvars. Pvars for which the minimum value is deter¬ 
mined. 


Returned Value- 

max-pvar Temporary numeric pvar. In each active processor, contains 

the minimum of the corresponding values of the supplied num¬ 
eric-pvar arguments. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This returns a pvar that contains in each processor the minimum of the 
corresponding values of the supplied numeric-pvars in that processor. 


617 




min!! 


*Lisp Dictionary 


Examples- 

(ppp (min!! (mod!! (self-address! !) (!! 2)) 

(mod!! (self-address!!) (!! 3)))) => 

01000101000101 . . . 


Notes 


References 
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minusp!! [Function] 

Performs a parallel test for negative values on the supplied pvar. 


Syntax- 

minusp!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Tested in parallel for negative values. 


Returned Value- 

minusp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of numeric-pvar is 
negative. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The pvar returned by this predicate contains t for each processor where the value 
of the argument numeric-pvar is less than zero, and nil in all others. 
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Examples- 

Notes- 

(minusp!! (!! -1)) <=> t!! 

(minusp!! (!! -0.0)) <=> nil!! 

References- 


620 











*Lisp Dictionary 


mod!! 


mod!! [Function] 

Performs a parallel modulo operation on the supplied pvars. 


Syntax- 

mod!! numeric-pvar divisor-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Pvar for which modulo remainder 

is calculated. 

divisor-pvar Integer pvar. Pvar by which numeric-pvar is divided. 

Returned Value- 

remainder-pvar Temporary numeric pvar, of same type as numeric-pvar. In 
each active processor, contains the result of dividing the value 
of numeric-pvar modulo the value of divisor-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function mod. It is an error if 
numeric-pvar contains zero in any processor. 
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Examples-- 

(ppp (mod!! (self-address!!) (!! 5))) => 

012340123401 234. . . 

Notes- 

References- 
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most-negative-float!! [Function] 

Returns a pvar containing the floating-point value that is closest to negative infinity 
and representable in the format of the supplied floating-point pvar. 


Syntax- 

most-negative-float!! floating-point-pvar 


Arguments- 

floating-point-pvar 

Floating-point pvar. Determines format of returned pvar. 


Returned Value- 

most-neg-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the floating-point value closest to negative infinity that is 
representable in the same format (single- or double-precision) 
as the corresponding value oi floating-point-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a floating-point pvar with the same format (single- or double¬ 
precision) as the argument floating-point-pvar. In each processor, the returned 
value is the floating point number closest to negative infinity that can be repre¬ 
sented by the CM in the same floating-point format as floating-point-pvar. 
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Examples- 

The argument floating-point-pvar may be any floating point pvar of the required 
format. For example, 

(most-negative-float!! (!! 0.0)) <=> (!! -3.4028235e38) 

The same result would be obtained with an argument of (!! 5.8) or with any single¬ 
precision floating-point pvar. 

Notes- 


References- 

See also these related floating-point pvar limit functions: 
float-epsilon!! least-negative-float!! least-positive-float!! 

most-positive-float!! negative-float-epsilon!! 
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most-positive-float!! [ Function] 

Returns a pvar containing the floating-point value that is closest to positive infinity and 
representable in the format of the supplied floating-point pvar. 


Syntax- 

most-positive-float!! floating-point-pvar 


Arguments- 

floating-point-pvar 

Floating-point pvar. Determines format of returned pvar. 


Returned Value- 

most-pos-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the floating-point value closest to positive infinity and 
representable in the same format as the corresponding value of 
floating-point-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a floating-point pvar with the same format (single- or double¬ 
precision) as the argument floating-point-pvar. In each processor, the returned 
value is the floating point number closest to positive infinity that can be repre¬ 
sented by the CM in the same floating-point format as floating-point-pvar. 
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Examples-- 

The argument floating-point-pvar may be any floating point pvar of the required 
format. For example, 

(most-positive-float!! (!! 0.0)) <=> (!! 3.4028235e38) 

The same result would be obtained with an argument of (!! 5.8) or with any single¬ 
precision floating-point pvar. 

Notes- 

References- 

See also these related floating-point pvar limit functions: 

float-epsilon!! least-negative-float!! least-positive-float!! 

most-negative-float!! negative-float-epsilon!! 
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negative-float-epsilon!! [Function] 

Returns a pvar containing the smallest negative floating-point value representable in 
the format of the supplied floating-point pvar. 


Syntax- 

negative-float-epsilon!! floating-point-pvar 


Arguments- 

floating-point-pvar 

Floating-point pvar. Determines format of returned pvar. 


Returned Value- 

epsilon-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the smallest negative value representable in the same for¬ 
mat as the corresponding value of floating-point-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, the value returned by negative-float-epsilon!! is the smallest 
negative floating-point number e that can be represented by the CM in the same 
floating point format as floating-point-pvar and for which 

(not (= (float 1 e ) (- (float 1 e) e))) 

is true when evaluated. 
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Examples 


Notes 


References- 

See also these related floating-point pvar limit functions: 
float-epsilon!! least-negative-float!! least-positive-float!! 

most-negative-float!! most-positive-float!! 
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*news [ * Defun] 

Performs grid (NEWS) communication, copying values from the source pvar to the des¬ 
tination pvar. 


Syntax- 

‘news source-pvar dest-pvar &rest relative-coordinate-integers 


Arguments- 

source-pvar Pvar expression. Pvar from which values are copied. 

dest-pvar Pvar expression. Pvar in which values are stored. 

relative-coordinate-integers 

Series of integers. Specifies relative distance over which copy 
takes place along each dimension of the current VP set. The 
number of arguments must be equal to the rank of the current 
machine configuration. 


Returned Value- 

nil Executed for side effect only. 


Side Effects- 

Destructively alters dest-pvar to contain values from source-pvar transmitted 
across the grid. 


Description- 

This function does near-neighbor store communication. Each active processor in 
the current VP set takes the value of source-pvar and stores it in the supplied 
dest-pvar, in the processor that is relative-coordinate-integers away across the 
n-dimensional grid of the current VP set. 
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The source-pvar argument is evaluated only by processors in the currently selected 
set, but the dest-pvar argument can be modified in any processor. In other words, 
even though only active processors transmit values from source-pvar, values can be 
received and stored in dest-pvar by any processor, active or not: 

The relative-coordinate-integer arguments specify a single relative grid address 
used by all active processors in determining the address of the destination, i.e., if 
the nth relative-coordinate-integer argument is the value j, then each active proces¬ 
sor will transmit a value to the processor j units away along dimension n. 

The grid addresses calculated by a *news operation are toroidal, i.e., there are no 
upper or lower bounds on the values of the relative-coordinate-integer arguments. 
Where grid addresses are produced that specify processors off the edge of the cur¬ 
rent grid, those addresses wrap around to the opposite edge of the grid. 


Examples- 

The *news macro can be used to perform global shifts of data across processor 
grids of any dimension. However, the macro is most commonly used on 
two-dimensional grids, where each processor has four neighbors, one each to the 
“left” and “right” along dimension 0, and one each “up” and “down” along 
dimension 1. 

The following expressions define such a grid, along with two pvars that will be used 
in the following examples. 

(*cold-boot :initial-dimensions '(32 16)) 

(*defvar source (random!! (!! 10))) 

(♦defvar dest) 

A call to ppp displays the grid of values stored in the source pvar. 

(ppp source :mode :grid :end '(4 4) :format "~2D ") 


7 9 8 6 
9 5 2 7 
6 2 4 2 

8 5 9 1 
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The following example of a call to *news shifts the entire grid over 1 to the right and 
down 1. Values are wrapped around from the right and lower edges to the left and 
upper edges. 

(♦news source dest 1 1) 

(ppp dest :mode :grid :end '(4 4 ) .-format "~2D ") 

8 5 8 1 

6 7 9 8 

8 9 5 2 

4 6 2 4 

The next example shows that the value of the dest-pvar in unselected processors 
can be altered by a call to *news. The processors in the even columns, which are 
selected, send data to the processors in the odd columns, which are not selected. 
Even though the processors in the odd columns are deselected, they may still re- 
cieve and store values. 

(♦set dest (!! 0)) 

(♦when (evenp!! (self-address-grid!! (!! 0))) 

(♦news source dest 1 0)) 

(PPP dest :mode -.grid : end '(4 4 ) -.format "~2D ") 

0 7 0 8 

0 9 0 2 

0 6 0 4 

0 8 0 9 


Notes- 

Notice that 'news is to news!! as *pset is to pref!!. Thus, while ‘news sends infor¬ 
mation to processors, news!! retrieves information from processors. Like ‘news, 
news!! assumes a toroidal arrangement of grid addresses, i.e., addresses wrap 
around the grid. 

Performance Note: 

Although seemingly symmetric, the CM-2 *Lisp implementation of news!! is 
faster than the CM-2 *Lisp implementation of ‘news. 
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Usage Note: 

The grid address assigned to a processor by a one-dimensional VP set is not the 
same as the processor’s send address. For example, given the one-dimensional 
grid defined by 

(*cold-boot :initial-dimensions 

(list *minimum-size-for-vp-set*)) 

the following expression displays in send address (:mode :cube) order the 
send addresses of a sample set of processors 

(ppp (self-address!!) :mode :cube :start 24 rend 40) 

24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 

and this expression displays the grid addresses of the same processors in send 
address order: 

(ppp (self-address-grid!! (!! 0)) rmode rcube 

:start 24 :end 40) 

24 25 26 27 28 29 30 31 48 49 50 51 52 53 54 55 

Notice that the grid addresses of the last eight processors in this example are 
different from their send addresses. In general, there is no simple way to relate 
the grid address assigned to a processor by a VP to the send address of that 
processor except by the *Lisp address conversion functions cube-from-grid- 
address, cube-from-vp-grid-address, grid-from-cube-address, and grid- 
from-vp-cube-address. The assignment depends on such factors as the size 
and shape of the VP set, and on the number of physical processors attached. 

Of course, if the grid addresses are displayed in grid address (:mode .-grid) 
order, the addresses displayed will be sequential: 

(ppp (self-address-grid!! (!! 0)) :mode :grid 

:start 24 :end 40) 


24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 
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However, in this example, the processors for which the addresses are being 
displayed are not the same as in the previous two examples. Displaying proces¬ 
sor grid addresses in grid address order by definition displays the addresses of 
those processors whose grid addresses are sequential. 

The errors produced by neglecting this distinction are more pervasive than 
these examples demonstrate. For example, it is a common mistake to expect the 
expression 

(PPP (news!! (self-address!!) 1) :mode :cube 

.•start 24 :end 40) 

to display a series of sequential send addresses. In fact, it displays this: 

24 25 26 27 28 29 30 31 48 33 34 35 36 37 38 39 

The following expression produces the expected result: 

(ppp (news!! (self-address-grid!! (!! 0)) 1) 

:mode :grid :start 24 :end 40) 


24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 


References- 

See also these related NEWS communication operators: 

news!! news-border!! 

* news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 

See also these related processor communication operators: 

pref!! *pset 
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news!! [Macro] 

Performs grid (NEWS) communication, returning a pvar containing values copied 
from the supplied pvar. 


Syntax- 

news!! source-pvar &rest relative-coordinate-integers 


Arguments-- 

source-pvar Pvar expression. Pvar from which values are copied. 

relative-coordinate-integers 

Set of integers. Specifies relative distance over which copy 
takes place along each dimension of the current VP set. The 
number of arguments must be equal to the rank of the current 
machine configuration. 


Returned Value- 

news-value-pvar Temporary pvar, of same type as source-pvar. In each active 
processor, contains a copy of the value of source-pvar from the 
processor specified by the set of relative-coordinate-integers. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This macro does near-neighbor fetch communication. Each processor in the cur¬ 
rently selected set retrieves the value of source-pvar from the processor that is 
relative-coordinate-integers away across the n-dimensional grid of the current VP 
set. 

Even though only active processors retrieve values from source-pvar, values can be 
retrieved from any processor, not just those in the currently selected set. In other 
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words, it is legal for the grid address specified by relative-coordinate-integers to 
cause values to be retrieved from processors that are not in the currently selected 
set. 

The relative-coordinate-integer arguments specify a single relative grid address 
used by all active processors in determining the address of the destination, i.e., if 
the nth relative-coordinate-integer argument is the value j, then each active proces¬ 
sor will retrieve a value from the processor j units away along dimension n. 

The grid addresses calculated by a news! ! operation are toroidal, i.e., there are no 
upper or lower bounds on the values of the relative-coordinate-integer arguments. 
Where grid addresses are produced that specify processors off the edge of the cur¬ 
rent grid, those addresses wrap around to the opposite edge of the grid. 


Examples- 

The news!! macro can be used to perform global shifts of data across processor 
grids of any dimension. However, the macro is most commonly used on 
two-dimensional grids, where each processor has four neighbors, one each to the 
“left” and “right” along dimension 0, and one each “up” and “down” along 
dimension 1. 

The following expressions define such a grid, along with two pvars that will be used 
in the following examples. 

(*cold-boot :initial-dimensions '(32 16)) 

(*defvar source (random!! (!! 10))) 

(*defvar dest (!! 0)) 

A call to ppp displays the grid of values stored in the source pvar. 

(ppp source :mode :grid :end '(4 4) :format "~2D ") 

7 9 8 6 

9 5 2 7 

6 2 4 2 

8 5 9 1 
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The following example of a call to news! ! shifts the entire grid over 1 to the left and 
up 1. Values are wrapped around from the left and upper edges to the right and 
bottom edges (not shown). 

(ppp (news!! source 1 1) :mode :grid :end '(4 4) 

:format ""2D ") 


5 2 7 4 

2 4 2 5 

5 9 13 

6 7 6 1 

The next example shows that the value of the source-pvar in unselected processors 
can be retrieved by selected processsors during a call to news!!. The processors in 
the even columns, which are selected, retrieve data from the processors in the odd 
columns, which are not selected. 

(*set dest (!! 0)) 

(*when (evenp!! (self-address-grid!! (!! 0))) 

(*set dest (news!! source 10))) 

(ppp dest :mode :grid :end '(4 4) :format "~2D ") 


9 0 6 0 

5 0 7 0 

2 0 2 0 
5 0 10 

The source-pvar argument to news!! is evaluated only in those processors from 
which data is being retrieved, not in the processors doing the retrieving. This 
means that operations signalling an error when the entire set of processors is se¬ 
lected may be perfectly legal when the currently selected set is restricted to a subset 
of processors. For example, consider the expression 

(*when (evenp!! (self-address-grid!! (!! 0))) 

(*set dest 
(round!! 

(news!! (/!! (!! 24) (self-address-grid!! (!! 0))) 

1 0 )))) 
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(ppp dest :mode :grid :end '(4 4) :format "~2D ") 


24 0 8 0 

24 0 8 0 

24 0 8 0 

24 0 8 0 

If the /!! operation in this example was performed with the entire set of processors 
selected, then a division by 0 would have occurred in the left-most column of pro¬ 
cessors because (self-address-grid!! (!! 0)) returns 0 for each processor in that 
column. The division was actually performed only in the processors belonging to 
the odd columns, i.e., those processors having data retrieved from them, so no er¬ 
ror was signalled. 


Notes- 

Notice that news!! is to *news as pref!! is to *pset. Thus, while news!! retrieves 
information from processors, ‘news sends information to processors. Like news!!, 
*news assumes a toroidal arrangement of grid addresses, i.e., addresses wrap 
around the grid. 

Performance Notes: 

Although seemingly symmetric, the CM-2 *Lisp implementation of news!! is 
faster than the CM-2 *Lisp implementation of *news. 

Also, when news! ! is invoked with relative coordinates that are powers of two, 
as in 

(news!! pvar 8 16) 

the CM-2 implementation of *Lisp uses special Paris instructions that are able 
to quickly retrieve the data. The above call to news!! is therefore signficantly 
faster than a call to news!! with non-power-of-two arguments, such as 

(news!! pvar 7 15) 
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Usage Note: 

The grid address assigned to a processor by a one-dimensional VP set is not the 
same as the processor’s send address. For example, given the one-dimensional 
grid defined by 

(*cold-boot :initial-dimensions 

(list *minimum-size-for-vp-set*)) 

the following expression displays in send address (:mode :cube) order the 
send addresses of a sample set of processors 

(ppp (self-address!!) :mode :cube :start 24 :end 40) 

24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 

and this expression displays the grid addresses of the same processors in send 
address order: 

(ppp (self-address-grid!! (!! 0)) :mode :cube 

:start 24 :end 40) 


24 25 26 27 28 29 30 31 48 49 50 51 52 53 54 55 

Notice that the grid addresses of the last eight processors in this example are 
different from their send addresses. In general, there is no simple way to relate 
the grid address assigned to a processor by a VP to the send address of that 
processor except by the *Lisp address conversion functions cube-from-grid- 
address, cube-from-vp-grid-address, grid-from-cube-address, and grid- 
from-vp-cube-address. The assignment depends on such factors as the size 
and shape of the VP set, and on the number of physical processors attached. 

Of course, if the grid addresses are displayed in grid address (:mode :grid) 
order, the addresses displayed will be sequential: 

(ppp (self-address-grid!! (!! 0)) :mode :grid 

:start 24 :end 40) 

24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 
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However, in this example, the processors for which the addresses are being 
displayed are not the same as in the previous two examples. Displaying proces¬ 
sor grid addresses in grid address order by definition displays the addresses of 
those processors whose grid addresses are sequential. 

The errors produced by neglecting this distinction are more pervasive than 
these examples demonstrate. For example, it is a common mistake to expect the 
expression 

(PPP (news!! (self-address!!) 1) :mode :cube 

:start 24 :end 40) 

to display a series of sequential send addresses. In fact, it displays this: 

24 25 26 27 28 29 30 31 48 33 34 35 36 37 38 39 

The following expression produces the expected result: 

(ppp (news!! (self-address-grid!! (!! 0)) 1) 

-.mode -.grid : start 24 : end 40) 


24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 


References- 

See also these related NEWS communication operators: 

*news news-border!! 

’news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 

See also these related processor communication operators: 

pref!! *pset 
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news-border!! [Macro] 

Performs grid (NEWS) communication, returning a pvar containing values copied 
from the supplied source pvar, with references off the grid satisfied by the supplied 
border pvar. 


Syntax- 

news-border!! source-pvar border-pvar &rest relative-coordinate-integers 


Arguments- 

source-pvar Pvar expression. Pvar from which values are copied. 

border-pvar Pvar expression. Value returned for all references off the grid. 

relative-coordinate-integers 

Set of integers. Specifies relative distance over which copy 
takes place along each dimension of the current VP set. The 
number of arguments must be equal to the rank of the current 
machine configuration. 


Returned Value- 

news-value-pvar Temporary pvar. In each active processor, contains a copy of 
the value of source-pvar in the processor specified by the set of 
relative-coordinate-integers, or the value of border-pvar, where 
the location specified is off the grid. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This macro performs the same operation as news!!, with the exception that, wher¬ 
ever a processor would be directed to retrieve a value from a location off the grid of 
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the current VP set, the processor instead returns the value of the supplied border- 
pvar. 


Examples- 

A sample call to news-border!! is 

(news-border!! pvar border-pvar 1 1) 

The news-border!! macro can be used to perform global shifts of data with a spe¬ 
cific “boundary” value stored in all processors that attempt to read information 
from outside the boundaries of the grid. For example, given the two-dimensional 
grid configuration defined by 

(♦cold-boot :initial-dimensions '(128 128)) 

the expression 

(ppp (news-border!! 

(self-address-grid!! (!! 0)) (!! -1) -1 -1) 

-.mode :grid 
:end '(4 4) 

:format "~2D ") 

performs a diagonal shift of data “downwards” and “rightwards” across the grid, 
producing the following output: 

-l -l -l -l 
-10 12 
-10 12 
-10 12 

The value -1 is stored into processors along the “top” and “left” edges of the grid 
because these are the processors that attempt to read outside the grid in this opera¬ 
tion. 


642 




*Lisp Dictionary 


news-border!! 


Notes 


References- 

See also these related NEWS communication operators: 

*news news!! 

* news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relati ve-p!! off-vp-grid-border-p!! 

See also these related processor communication operators: 

pref!! *pset 
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*news-direction [* Defun] 

Performs NEWS (grid) communication along a single dimension, copying values from 
the source pvar to the destination pvar. 


Syntax- 

•news-direction source-pvar destination-pvar 

dimension-scalar distance-scalar 


Arguments 


source-pvar 

destination-pvar 

dimension-scalar 

distance-scalar 


Pvar expression. Pvar from which values are copied. 
Pvar expression. Pvar into which values are stored. 
Integer. Dimension along which to perform copy. 
Integer. Distance over which values are copied. 


Returned Value- 

nil Executed for side effect only. 


Side Effects- 

Destructively alters destination-pvar to contain values from source-pvar trans¬ 
mitted across the NEWS grid. 


Description- 

Performs a *news operation on the source pvar, along the specified dimension and 
at the specified distance. Each active processor in the current VP set sends source- 
pvar data to the processor that is distance-scalar processors away along the dimen¬ 
sion-scalar axis, and stores it in destination-pvar. 

The source-pvar and destination-pvar parameters must both be in the current VP 
set. 
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The source-pvar argument is evaluated only by processors in the currently selected 
set, but the destination-pvar argument can be modified in any processor. In other 
words, even though only active processors transmit values from source-pvar, val¬ 
ues can be received and stored in destination-pvar by any processor, not just those 
in the currently selected set. 

The dimension-scalar parameter must be an integer in the range [0..(N -1)], where 
N is the number of dimensions defined for the current VP set. 

The distance-scalar parameter must be an integer. The sign of this value deter¬ 
mines in which direction along the specified dimension data is sent. Grid ad¬ 
dresses wrap around where necessary. 

This function permits *news operations along a given dimension without requiring 
specification of the total number of dimensions in the current VP set. Thus, assum¬ 
ing a three-dimensional machine configuration, 

(*news-direction my-pvar my-result 2 3) 

<=> 

(*news my-pvar my-result 003) 


Examples- 

This function is particularly useful when writing subroutines that must do NEWS 
operations along a particular dimension of the currently defined grid but may be 
called with VP sets of differing ranks active. 

(defun shift-upward-along-y-axis (dest-pvar 

source-pvar 

distance) 

(*news-direction source-pvar dest-pvar 1 (- distance))) 
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Notes 


References- 

See also these related NEWS communication operators: 

*news news!! news-border!! 

news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 

See also these related processor communication operators: 

pref!! *pset 


647 






*Lisp Dictionary 


news-direction!! 


news-direction!! [Macro] 

Performs NEWS (grid) communication along a specified dimension, returning a pvar 
containing values copied from the supplied pvar. 


Syntax- 

news-direction!! source-pvar dimension-scalar distance-scalar 


Arguments- 

source-pvar Pvar expression. Pvar from which values are copied. 

dimension-scalar Integer. Dimension along which to perform copy. 
distance-scalar Integer. Distance over which values are copied. 

Returned Value- 

news-value-pvar Temporary pvar, of same type as source-pvar. In each active 
processor, contains a copy of the value of source-pvar in the 
processor distance-scalar away along the dimension specified 
by dimension-scalar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

Performs a news!! operation on the specified pvar, along the specified dimension 
and at the specified distance. Each active processor in the current VP set retrieves 
source-pvar data from the processor that is distance-scalar processors away along 
the dimension-scalar axis. 

The source-pvar parameter must be in the current VP set. 
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Even though only active processors retrieve values from source-pvar, values can be 
retrieved from any processor, not just those in the currently selected set. In other 
words, it is legal for the grid address specified by dimension-scalar and distance- 
scalar to cause values to be retrieved from processors that are not in the currently 
selected set. 

The dimension-scalar parameter must be an integer in the range [0 ..(N -1)], where 
N is the number of dimensions defined for the current VP set. 

The distance-scalar parameter must be an integer. The sign of this value deter¬ 
mines from which direction along the specified dimension data is retrieved. Grid 
addresses wrap around where necessary. 

This function permits news!! operations along a given dimension without requir¬ 
ing specification of the total number of dimensions in the current VP set. Thus, 
assuming a three-dimensional machine configuration has been defined, the 
following equivalence holds: 

(news-direction!! my-pvar 1 2) 

<=> 

(news!! my-pvar 020) 


Examples- 

This function is particularly useful when writing subroutines that must do NEWS 
operations along a particular dimension of the currently defined grid but may be 
called with VP sets of differing ranks active. 

(defun shift-upward-along-y-axis (pvar distance) 
(news-direction!! pvar 1 distance))) 
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Notes 


References- 

See also these related NEWS communication operators: 

*news news!! news-border!! 

"news-direction 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 

See also these related processor communication operators: 

pref!! *pset 
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next-power-of-two- > = [Function] 

Returns the next power of two greater than or equal to the supplied integer. 


Syntax- 

next-power-of-two->= positive-integer 


Arguments- 

positive-integer Integer. Value for which the next higher power of two is deter¬ 
mined. 


Returned Value- 

power-of-two Integer. Next power of two greater than or equal to positive-in¬ 
teger. 


Side Effects 

None. 


Description- 

This function returns the first consecutive integer satisfying power-of-two-p that 
is greater than or equal to positive-integer. 
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Examples 


(next-power-of-two->= 356) => 512 


Notes- 

Usage Note: 

This function is useful in computing the dimensions of VP sets, because each 
dimension of a VP set must be an integral power of two in size, and the total 
number of processors in a VP set must be a power of two multiple of the num¬ 
ber of physical processors available. 

For instance, if a data file has 23,432 items, a call to next-power-of-two->=, 
specifically 

(next-power-of-two->= 23432) => 32768 

can be used to determine that a VP set of size 32768 is required to process the 
data. 


References- 

See also the related predicate power-of-two-p. 

The next-power-of-two->= function is most useful in combination with the 
following VP set definition operators: 

def-vp-set create-vp-set let-vp-set 
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not!! [Function] 

Performs a parallel logical negation on the supplied pvar. 

Syntax- 

not!! pvar 

Arguments- 

pvar Pvar expression. Pvar for which the logical negation is deter¬ 

mined. 

Returned Value- 

not-pvar Temporary boolean pvar. Contains t in those active processors 

where pvar contains the value nil. Contains nil in all other pro¬ 
cessors. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This returns t for all processors in which pvar is nil, and nil otherwise. 
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Examples 


Notes 


References- 

See also the related global operators: 


and 

•integer-length 

•logand 

logior 

•logxor 

•max 

min 

*or 

•sum 

xor 




See also the related logical operators: 

and!! or!! xor!! 
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notany!! [Function] 

Tests in parallel whether the supplied pvar predicate is false for every set of elements 
having the same indices in the supplied sequence pvars. 


Syntax- 

notany!! predicate sequence-pvar &rest sequence-pvars 


Arguments- 

predicate Boolean pvar predicate. Used to test elements of sequences in 

the sequence-pvar arguments. Must take as many arguments as 
the number of sequence-pvar arguments supplied. 

sequence-pvar, sequence-pvars 

Sequence pvars. Pvars containing, in each processor, 
sequences to be tested by predicate. 


Returned Value- 

notany-pvar Temporary boolean pvar. Contains the value t in each active 

processor in which every set of elements taken from the se¬ 
quences of the sequence-pvars fails the predicate. Contains nil 
in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The notany!! function returns a boolean pvar indicating in each processor whether 
the supplied predicate is false for every set of elements with the same indices in the 
sequences of the supplied sequence-pvars. 
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In each processor, the predicate is first applied to the index 0 elements of the 
sequences in the sequence-pvars, then to the index 1 elements, and so on. The nth 
time predicate is called, it is applied to the nth element of each of the sequences. If 
predicate returns t in any processor, that processor is temporarily removed from 
the currently selected set for the remainder of the operation. The operation contin¬ 
ues until the shortest of the sequence-pvars is exhausted, or until no processors 
remain selected. 

The pvar returned by notany! ! contains t in each processor where predicate returns 
the value nil for every set of sequence elements. If predicate returns t for any set of 
sequence elements in a given processor, notany! ! returns nil in that processor. 


Examples- 

(notany!! 'equalp!! (!! #(1 2 3)) (!! #(9 4 1))) <=> t!! 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See the related functions every!!, notevery!!, and some!!. 
See also the general mapping function amap!!. 
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notevery! ! [Function] 

Tests in parallel whether the supplied pvar predicate is false for at least one set of ele¬ 
ments having the same indices in the supplied sequence pvars. 


Syntax- 

notevery!! predicate sequence-pvar &rest sequence-pvars 


Arguments- 

predicate Boolean pvar predicate. Used to test elements of sequences in 

the sequence-pvar arguments. Must take as many arguments as 
the number of sequence-pvar arguments supplied. 

sequence-pvar, sequence-pvars 

Sequence pvars. Pvars containing, in each processor, 
sequences to be tested by predicate. 


Returned Value- 

notevery-pvar Temporary boolean pvar. Contains the value t in each active 
processor in which at least one set of elements having the same 
indices in the sequences of the sequence-pvars fails the 
predicate. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The notevery!! function returns a boolean pvar indicating in each processor 
whether the supplied predicate is false for at least one set of elements with the same 
indices in the sequences of the supplied sequence-pvars. 
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In each processor, the predicate is first applied to the index 0 elements of the 
sequences in the sequence-pvars, then to the index 1 elements, and so on. The nth 
time predicate is called, it is applied to the nth element of each of the sequences. If 
predicate returns nil in any processor, that processor is temporarily removed from 
the currently selected set for the remainder of the operation. The operation contin¬ 
ues until the shortest of the sequence-pvars is exhausted, or until no processors 
remain selected. 

The pvar returned by notevery!! contains t in each processor where predicate re¬ 
turns the value nil for at least one set of sequence elements. If predicate returns t for 
every set of sequence elements in a given processor, notevery!! returns nil in that 
processor. 


Examples- 

(notevery!! 'equalp!! (!! #(1 2 3)) (!! #(1 2 4))) <=> t!! 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See the related functions every!!, notany!!, and some!!. 
See also the general mapping function amap!!. 
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*n reverse [* Defun] 

Destructively reverses each sequence stored in the supplied sequence pvar. 

Syntax- 

*nreverse sequence-pvar 


Arguments- 

sequence-pvar Sequence pvar. Pvar containing sequences to be reversed. 

Returned Value- 

sequence-pvar Sequence pvar. The supplied sequence-pvar with each of its se¬ 

quences destructively reversed. 

Side Effects- 

None. 

Description- 

The function *nreverse destructively modifies sequence-pvar to contain its ele¬ 
ments in reverse order. The argument sequence-pvar must be a vector pvar. 
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Examples- 

(*nreverse (!! #(1 2 3 4))) <=> (!! #(4 321)) 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See also these related *Lisp sequence operators: 

copy-seq!! *f ill length!! 

reduce!! reverse!! subseq!! 

See also the generalized array mapping functions amap!! and *map. 
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nsubstitute!! [Function] 

Performs a destructive parallel substitution operation on the supplied sequence pvar, 
replacing specified old items with new items. 


Syntax- 

nsubstitute!! new-item old-item sequence-pvar 

&key :from-end :test :test-not 
:start :end mount :key 


Arguments- 

new-item Pvar expression, of same data type as sequence-pvar. Item to 

substitute for old-item in each processor. 

old-item Pvar expression, of same data type as sequence-pvar. Item to be 

replaced in each processor. 

sequence-pvar Sequence pvar. Pvar containing sequences to be modified. 

:from-end Boolean pvar. Whether to begin substitution from end of se¬ 

quence in each processor. 

:test Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

:test-not Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a nil result. 

: start Integer pvar. Index of sequence element at which substitution 

starts in each processor. If not specified, search begins with 
first element. Zero-based. 

:end Integer pvar. Index of sequence element at which substitution 

ends in each processor. If not specified, search continues to 
end of sequence. Zero-based. 

: count Integer pvar. Maximum number of replacements to perform in 

each processor. Defaults to (length!! sequence-pvar) 
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:key One-argument pvar accessor function. Applied to 

sequence-pvar before search is performed. 


Returned Value- 

sequence-pvar Sequence pvar. The supplied sequence-pvar with each of its se¬ 
quences destructively modified. 


Side Effects- 

Destructively modifies sequence-pvar, replacing elements matching old-item with 
copies of new-item. 


Description- 

This function is the parallel equivalent of the Common Lisp nsubstitute func- 
tion.The nsubstitute!!, nsubstitute-if!!, and nsubstitute-if-not!! functions are 
destructive versions of the substitute!! functions. 

In each processor, the function nsubstitute! ! searches sequence-pvar for elements 
that match old-item. Each such element is destructively modified to contain the 
value specified by new-item. 

Elements of sequence-pvar are tested against old-item with the eql!! operator un¬ 
less another comparison operator is supplied as either of the :test or :test-not ar¬ 
guments. The keywords :test and :test-not may not be used together. A lambda 
form that takes two pvar arguments and returns a boolean pvar result may be 
supplied as either the :test and :test-not argument. 

The keyword :from-end takes a boolean pvar that specifies from which end ofse- 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords: start and :end define a subsequence to be operated on 
in each processor. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 
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The :count keyword argument must be a positive integer pvar with values less than 
or equal to (length !! sequence-pvar ). In each processor at most count elements are 
substituted. 


Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 
count!! count-if!! count-if-not!! 

find!! find-if!! f ind-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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nsubstitute-if!! [Function] 

Performs a destructive parallel substitution operation on the supplied sequence pvar 
replacing items that satisfy the supplied test with new items. 


Syntax- 

nsubstitute-if!! new-item test sequence-pvar 

&key :from-end :start :end :count :key 


Arguments- 

new-item Pvar expression, of same data type as sequence-pvar. Item to 

substitute for elements satisfying test in each processor. 

test One-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

sequence-pvar Sequence pvar. Pvar containing sequences to be modified. 

:from-end Boolean pvar. Whether to begin substitution from end of se¬ 

quence in each processor. 

: start Integer pvar. Index of sequence element at which substitution 

starts in each processor. If not specified, search begins with 
first element. Zero-based. 

:end Integer pvar. Index of sequence element at which substitution 

ends in each processor. If not specified, search continues to 
end of sequence. Zero-based. 

: count Integer pvar. Maximum number of replacements to perform in 

each processor. Defaults to (length!! sequence-pvar) 

:key One-argument pvar accessor function. Applied to 

sequence-pvar before search is performed. 


Returned Value- 

sequence-pvar Sequence pvar. The supplied sequence-pvar with each of its se¬ 
quences destructively modified. 
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Side Effects- 

Destructively modifies sequence-pvar, replacing elements that satisfy the supplied 
test with copies of new-item. 


Description- 

This function is the parallel equivalent of the Common Lisp nsubstitute-if func- 
tion.The nsubstitute!!, nsubstitute-if!!, and nsubstitute-if-not!! functions are 
destructive versions of the substitute!! functions. 

In each processor, the function nsubstitute-if!! searches sequence-pvar for ele¬ 
ments satisfying test. Each such element is destructively modified to contain the 
value specified by new-item. A lambda form that takes a single pvar argument and 
returns a boolean pvar result may be supplied as the test argument. 

The keyword :from-end takes a boolean pvar that specifies from which end of se¬ 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords: start and :end define a subsequence to be operated on 
in each processor. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 

The: count keyword argument must be a positive integer pvar with values less than 
or equal to (length \\ sequence-pvar). In each processor at most count elements are 
substituted. 


Examples 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 
count!! count-if!! count-if-not!! 

find!! find-if!! find-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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nsubstitute-if-not!! [Function] 

Performs a destructive parallel substitution operation on the supplied sequence pvar 
replacing items that fail the supplied test with new items. 

Syntax- 

nsubstitute-if-not!! new-item test sequence-pvar 

&key :from-end :start :end :count :key 


Arguments- 

new-item Pvar expression, of same data type as sequence-pvar. Item to 

substitute for elements failing test in each processor. 

test One-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

sequence-pvar Sequence pvar. Pvar containing sequences to be modified. 

:from-end Boolean pvar. Whether to begin substitution from end of se¬ 

quence in each processor. 

: start Integer pvar. Index of sequence element at which substitution 

starts in each processor. If not specified, search begins with 
first element. Zero-based. 

:end Integer pvar. Index of sequence element at which substitution 

ends in each processor. If not specified, search continues to 
end of sequence. Zero-based. 

: count Integer pvar. Maximum number of replacements to perform in 

each processor. Defaults to (length!! sequence-pvar) 

:key One-argument pvar accessor function. Applied to 

sequence-pvar before search is performed. 


Returned Value- 

sequence-pvar Sequence pvar. The supplied sequence-pvar with each of its se¬ 

quences destructively modified. 
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Side Effects- 

Destructively modifies sequence-pvar, replacing elements that fail the supplied test 
with copies of new-item. 


Description- 

This function is the parallel equivalent of the Common Lisp nsubstitute-if-not 
function.The nsubstitute!!, nsubstitute-if!!, and nsubstitute-if-not!! functions are 
destructive versions of the substitute!! functions. 

In each processor, the function nsubstitute-if-not!! searches sequence-pvar for 
elements failing test. Each such element is destructively modified to contain the 
value specified by new-item. A lambda form that takes a single pvar argument and 
returns a boolean pvar result may be supplied as the test argument. 

The keyword :from-end takes a boolean pvar that specifies from which end ofse- 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords: start and: end define a subsequence to be operated on 
in each processor. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 

The: count keyword argument must be a positive integer pvar with values less than 
or equal to (length V. sequence-pvar). In each processor at most count elements are 
substituted. 


Examples 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 

count!! count-if!! count-if-not!! 

find!! find—if!! find-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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null!! [Function] 

Performs a parallel test for nil values on the supplied pvar. 

Syntax- 

null!! pvar 

Arguments- 

pvar Pvar expression. Pvar to be tested for nil values. 

Returned Value- 

null-pvar Temporary boolean pvar. Contains t in those active processors 

where pvar contains the value nil. Contains nil in all other pro¬ 
cessors. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function is functionally equivalent to not!!. 
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Examples - 

Notes- 

References 
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numberp!! [Function] 

Performs a parallel test for numeric values on the supplied pvar. 

Syntax- 

numberp!! pvar 

Arguments- 

pvar Pvar expression. Pvar to be tested for numeric values. 

Returned Value- 

numberp-pvar Temporary boolean pvar. Contains t in those active processors 
where pvar contains a numeric value. Contains nil in all other 
active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This is the parallel equivalent of the Common Lisp function numberp. 
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Examples 

Notes — 


References- 

See also these related pvar data type predicates: 

booleanp!! characterp!! complexp!! 

floatp!! front-end-p!! integerp!! 

string-char-p!! structurep!! 

typep!! 
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oddp!! [Function] 

Performs a parallel test for odd values on the supplied integer pvar. 


Syntax- 

oddp!! integer-pvar 


Arguments- 

integer-pvar Integer pvar. Pvar to be tested for odd values. 


Returned Value- 

oddp-pvar Temporary boolean pvar. Contains t in each active processor 

where integer-pvar contains an odd value. Contains nil in all 
other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The pvar returned by this predicate contains t for each processor where the value 
of the argument integer-pvar is odd, and nil in all others. It is an error if any compo¬ 
nent of integer-pvar is not an integer. 


679 




oddp!! 


*Lisp Dictionary 


Examples - 

Notes- 

References 
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off-grid-border-p!! [Function] 

Performs a parallel test on the supplied pvar(s) for grid (NEWS) addresses that are 
outside the currently specified grid dimensions. 


Syntax- 

off-grid-border-p!! coordinate-pvar &rest coordinate-pvars 


Arguments- 

coordinate-pvar, coordinate-pvars 

Integer pvars. Pvars specifying a grid (NEWS) address in each 
processor. The number of arguments must be equal to the rank 
of the current machine configuration. 


Returned Value- 

off-gridp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding values of the coordinate- 
pvars specify a location outside the currently specified grid di¬ 
mensions. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function tests grid addresses for validity. In each processor, the grid address 
tested is the integer series constituted by that processor’s values of the coordinate- 
pvar arguments. This function determines whether or not these grid addresses are 
within the bounds defined by the current VP set. 

This function returns a boolean pvar that has the value t in each processor where 
the supplied coordinate-pvars specify a grid address that is invalid given the cur¬ 
rent grid dimensions, and nil otherwise. 
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Examples- 

This example defines a two-dimensional grid configuration, and generates a pair of 
pvars that contain random grid addresses. 

(*cold-boot :initial-dimensions '(4 4)) 

(*defvar x-coordinate (random!! (!! 6))) 

(*defvar y-coordinate (random!! (!! 6))) 

(ppp x-coordinate :mode :grid) 

4 5 5 5 

4 2 2 2 
2 15 3 

5 12 3 

(ppp y-coordinate :mode :grid) 

0 10 5 
0 0 2 4 
114 4 
5 3 11 

Some of the grid addresses specified by the pvars will lie outside the grid of the VP 
set. A call to off-grid-border-p!! determines which grid addresses actually do lie 
outside the grid. 

(PPP (off-grid-border-p!! x-coordinate y-coordinate) 
rmode :grid :format "~3S ") 

T T T T 

T NIL NIL T 

NIL NIL T T 

T NIL NIL NIL 


682 




*Lisp Dictionary 


off-grid-border-p!! 


Notes 


References- 

This function tests whether the supplied grid addresses are within the grid dimen¬ 
sions of the current VP set. See the related function off-vp-grid-border-p!! for a 
way to test grid addresses in VP sets other than the current one. 

See also these related NEWS communication operators: 

*news news!! news-border!! 

* news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-relative-direction-p!! 
off-grid-border-relative-p!! 

See also these related processor communication operators: 

pref!! *pset 
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off-grid-border-relative-direction-p!! [Function] 

Performs a parallel test for processors that access a location beyond the boundaries of 
the currently specified grid along the specified dimension. 


Syntax- 

off-grid-border-relative-direction-p! ! dimension-scalar distance-scalar 


Arguments- 

dimension-scalar Integer. Dimension along which to test references. 
distance-scalar Integer. Distance along dimension to test. 


Returned Value- 

off-gridp-pvar Temporary boolean pvar. Contains the value t in each active 
processor for which distance-scalar represents an access along 
the dimension specified by dimension-scalar that is beyond the 
boundary of the currently specified grid. Contains nil in all oth¬ 
er active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

Tests the relative grid addresses indicated by the specified dimension-scalar and 
distance-scalar for validity. A boolean pvar is returned. 

The dimension-scalar argument must be an integer that is in the range [0..(7V-1)], 
where N is the number of dimensions defined for the current VP set. 
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The distance-scalar argument must be an integer and may be negative. The sign of 
this value determines in which direction along the specified dimension relative ad¬ 
dresses are calculated. 

The return value of this function is a boolean pvar that contains t in each processor 
for which an invalid relative address is specified and nil elsewhere. 

If, for an active processor P in the current VP set, there exists another processor 
that is distance-scalar processors away along the dimension-scalar axis, then the 
result returned in processor P is nil. 


Examples- 

This function is similar to off-grid-border-p!! and off-grid-border-relative-p!!. 
However, it permits relative address verification along a single dimension without 
requiring specification of the total number of dimensions in the current VP set. 
Thus, the following forms are equivalent, 

(off-grid-border-relative-direction-p!! 1 5) 

<=> 

(off-grid-border-relative-p!! 0 5 0) 
assuming a three-dimensional machine configuration. 


Notes 


References- 

See also these related NEWS communication operators: 

"news news!! news-border!! 

‘news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 

See also these related processor communication operators: 

pref!! *pset 
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off-grid-border-relative-p!! [Function] 

Performs a parallel test on the supplied pvar(s) for relative grid (NEWS) addresses that 
are outside the currently specified grid dimensions. 


Syntax- 

off-grid-border-relative-p!! relative-coord-pvar &rest relative-coord-pvars 


Arguments- 

relative-coord-pvar, relative-coord-pvars 

Integer pvars. Pvars specifying a relative grid (NEWS) address 
in each processor. The number of arguments must be equal to 
the rank of the current machine configuration. 

Returned Value- 

off-gridp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding values of the relative- 
coord-pvars specify a location outside the currently specified 
grid dimensions. Contains nil in all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function tests relative grid addresses for validity. In each processor, the 
relative-coord-pvar arguments specify a relative grid address. Specifically, the y'th 
relative-coord-pvar argument specifies for each processor the distance between 
that processor and the processor to be referenced, along the yth dimension. The 
off-grid-border-relative-p!! function determines whether or not the relative grid 
address in each processor is within the bounds of the current grid configuration. 
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Examples- 

This example defines a two-dimensional grid configuration, and then makes a call 
to off-grid-border-relative-p! ! that tests the same relative grid address, (-1,-1), in 
each processor. As the result of this operation shows, the only processors for which 
this relative grid address is off the edge of the grid are those processors on the 
“top” and “left” edges of the grid. 

(*cold-boot :initial-dimensions '(128 128)) 

(ppp (off-grid-border-relative-p!! (!! -1) (!! -1)) 

:mode :grid rend '(4 4) :format M ~3S ") 

T T T T 

T NIL NIL NIL 

T NIL NIL NIL 

T NIL NIL NIL 

The off-grid-border-relative-p!! function can also be used to easily select all pro¬ 
cessors within two processors of the border. 

(*when (or!! (off-grid-border-relative-p!! (!! -2) (!! -2)) 
(off-grid-border-relative-p!! (!! 2) (!! 2))) 

(check-border-condition)) 
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Notes 


References- 

The off-grid-border-relative-p! ! function is similar to off-grid-border-pl! except 
that the relative-coord-pvars specify relative grid addresses rather than absolute 
addresses. 

See also these related NEWS communication operators: 

•news news!! news-border!! 

•news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-vp-grid-border-p!! 

See also these related processor communication operators: 

pref!! *pset 
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off-vp-grid-border-p!! [Function] 

Performs a parallel test on the supplied pvar(s) for grid (NEWS) addresses that are 
outside the grid dimensions of the supplied VP set. 


Syntax- 

off-vp-grid-border-p!! vp-set coordinate-pvar &rest coordinate-pvars 


Arguments- 

vp-set VP set object. The grid addresses specified by the supplied 

coordinate-pvars are tested to determine whether they are with¬ 
in the grid boundaries of vp-set. 

coordinate-pvar, coordinate-pvars 

Integer pvars. Pvars that specify a grid (NEWS) address in each 
processor. The number of coordinate-pvar arguments must be 
equal to the number of dimensions in vp-set. 

Returned Value- 

off-gridp-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding values of the coordinate- 
pvars specify a location outside the grid dimensions of vp-set. 
Contains nil in all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function tests grid addresses for validity relative to a specified VP set. 

The return value of off-vp-grid-border-p! ! is a boolean pvar. It contains t in each 
processor for which the local values of the coordinate-pvars specify an invalid grid 
address. In all other processors, nil is returned. 
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Examples- 

This example creates a two-dimensional VP set, two-d-vp-set, a one-dimensional 
VP set, my-vp-set, and a pair of pvars belonging to my-vp-set that contain 
random grid addresses within two-d-vp-set. 

(def-vp-set two-d-vp-set '(4 4)) 

(def-vp-set my-vp-set '(8)) 

(*defvar y-coordinate (random!! (!! 5)) nil my-vp-set)) 

(*defvar x-coordinate (random!! (!! 5)) nil my-vp-set)) 

(ppp x-coordinate) 

14130031 

(PPP y-coordinate) 

40223114 

A call to off-grid-border-p!!, specifically 

(*with-vp-set my-vp-set 

(ppp (off-vp-grid-border-p!! two-d-vp-set 

x-coordinate y-coordinate))) 

T T NIL NIL NIL NIL NIL T 

demonstrates that the coordinate pairs contained in processors 0, 1, and 7 of the 
two coordinate pvars are invalid for two-d-vp-set. 

As this example shows, it is not necessary for the coordinate-pvar arguments to 
belong to the specified vp~set , or to even have the same size (number of elements). 
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Notes 


References- 

This function is similar to off-grid-border-p! ! except that it permits testing of grid 
addresses within a specific VP set other than the current one. 

See also these related NEWS communication operators: 

"news news!! news-border!! 

* news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! 

See also these related processor communication operators: 

pref!! *pset 
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*or [* Defun] 

Takes the logical inclusive OR of all values in a pvar, returning a scalar value. 

Syntax- 

*or pvar-expression 

Arguments- 

pvar-expression Pvar expression. Pvar to which global inclusive OR is applied. 

Returned Value- 

or-scalar Scalar boolean value. The logical inclusive OR of the values in 

pvar. 

Side Effects- 

None. 


Description- 

The *or function is a global operator. It returns a scalar value of t if the value of 
pvar-expression in any active processor is non-nil, and returns nil otherwise. 

If there are no active processors, this function returns nil. 


695 



*Lisp Dictionary 



Examples- 

Two examples of the use of global operators such as ‘or are 

(*defun =t!! (pvar) (not (*or (not!! pvar))) 
(♦defun =ni1!! (pvar) (not (*or pvar))) 


Notes- 

To determine whether there are any processors currently selected, a handy idiom is 

(*or t!!) 

which returns t only if there are selected processors. 


References 


See also the related global operators: 


‘and 

‘integer-length 

‘logand 

‘logior 

‘logxor 

‘max 

*min 

*sum 

*xor 

See also the related logical operators: 


and!! 

not!! or!! 

xor!! 
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or!! [Macro] 

Performs a parallel logical inclusive OR operation in all active processors. 


Syntax- 

or!! &rest pvar-exprs 


Arguments- 

pvar-exprs Pvar expressions. Pvars to which parallel inclusive OR is 

applied. 


Returned Value- 

or-pvar Temporary boolean pvar. Contains in each active processor the 

logical inclusive OR of the corresponding values of the 
pvar-exprs. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The or!! function performs a parallel logical inclusive OR operation. It evaluates 
each of the supplied pvar-exprs in order, from left to right, in all active processors. 
As soon as one of the pvar-exprs evaluates to a non-nil value in a processor, that 
processor is removed from the currently selected set for the remainder of the or!!. 

The temporary pvar returned by or! ! contains the value of the last of the pvar-exprs 
evaluated in each processor. If no pvar-exprs are supplied, the pvar nil!! is re¬ 
turned. 

The function or!! provides a functionality for boolean pvars similar to that pro¬ 
vided by the Common Lisp function or for boolean values. 
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Examples- 

A simple example of the use of the or!! macro is 

(PPP (or!! (evenp!! (self-address!!)) 

(<!! (self-address!! (!! 3)))) 

:end 10) 

T T T NIL T NIL T NIL T NIL 


Notes- 

Language Note: 

Remember that or!! changes the currently selected set as it evaluates its argu¬ 
ments. This can have unwanted side effects in code that depends on unchang¬ 
ing selected sets, particularly code involving communication operators, such 
as scan!!. 

For example, the expressions 

(ppp (or!! (evenp!! (self-address!!)) 

(<!! (scan!! (self-address!!) '+!!) (!! 5))) 

:end 8) 

T T T T T NIL T NIL 

(ppp (or!! (<!! (scan!! (self-address!!) '+!!) (!! 5)) 
(evenp!! (self-address!!))) 

:end 8) 

T T T NIL T NIL T NIL 

exemplify a case in which using or! ! may cause a non-intuitive result because of 
its deselection properties. In the first expression, the scan!! operation is 
performed only in the odd processors. In the second expression, the scan! ! op¬ 
eration is performed in all processors, resulting in different set of displayed 
values. 
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This is the result of or!! deselecting those processors that satisfy any clause, 
before executing the next clause. One can avoid this in the following manner: 

(*let ((bl (evenp!! (self-address!!))) 

(b2 (<!! (scan!! (self-address!!) '+!!) (!! 3)))) 
(declare (type boolean-pvar bl b2)) 

(or!! bl b2)) 


References- 

See also the related global operators: 


and 

‘integer-length 

‘logand 

logior 

‘logxor 

‘max 

min 

‘or 

‘sum 

xor 




See also the related logical operators: 

and!! not!! xor!! 
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phase!! [ Function ] 

Returns a pvar containing the phase angle of the supplied complex pvar. 


Syntax- 

phase!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which the phase angle is calculated. 

Returned Value- 

phase-ang-pvar Numeric pvar. In each active processor, contains the phase 
angle of the corresponding complex value in numeric-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a temporary pvar containing in each processor the phase 
angle, in radians, of the complex value in numeric-pvar. Note: numeric-pvar need 
not explicitly contain complex values. Non-complex values are coerced to complex 
values with a zero imaginary component. 
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Examples- 

Notes- 

References- 

See also these related complex pvar operators: 

abs!! cis!! complex!! 

conjugate!! imagpart!! realpart!! 
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plusp!! [Function] 

Performs a parallel test for positive values on the supplied pvar. 


Syntax- 

plusp!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Tested in parallel for positive values. 


Returned Value- 

plusp-pvar Temporary boolean pvar. Contains the value t in each active 

processor where the corresponding value of numeric-pvar is 
positive. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The pvar returned by this predicate contains t for each processor where the value 
of the argument number-pvar is greater than zero, and nil in all others. 
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plusp!! 

Examples - 

Notes- 

References 
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position!! [Function] 

Performs a parallel search on a sequence pvar, returning in each processor the posi¬ 
tional index of the first sequence element matching the supplied item. 


Syntax- 

position!! item-pvar sequence-pvar &key :from-end :test :test-not 

:start :end :key 


Arguments- 

item-pvar Pvar expression. Item to match in the corresponding value of 

sequence-pvar. Must be of the same data type as the elements 
of sequence-pvar. 


sequence-pvar Sequence pvar. Contains sequences to be searched. 

:from-end Boolean pvar. Whether to begin search from end of sequence 

in all processors. Defaults to nil. 

: test Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

:test-not Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a nil result. 

: start Integer pvar. Index, zero-based, of sequence element at which 

search starts in each processor. If not specified, search begins 
with first element. 

:end Integer pvar. Index, zero-based, of sequence element at which 

search ends in each processor. If not specified, search contin¬ 
ues to end of sequence. 

:key One-argument pvar accessor function. Applied to each ele¬ 

ment in sequence-pvar before test is performed. 
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Returned Value- 

position-pvar Temporary pvar, of same data type as elements of sequence- 
pvar. In each active processor, contains the numeric index of 
the first element of sequence-pvar that matched item-pvar. Re¬ 
turns the value -1 in processors where no match was found. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp position function. 

In each processor, the function position !! searches sequence-pvar for elements that 
match item-pvar. It returns a pvar containing the index of the first match found in 
each processor. In any processor failing the search, the returned pvar contains -1. 

Elements of sequence-pvar are tested against item-pvar with the eql! ! operator un¬ 
less another comparison operator is supplied as either of the :test or :test-not ar¬ 
guments. The keywords :test and :test-not may not be used together. A lambda 
form that takes two pvar arguments and returns a boolean pvar result may be 
supplied as either the :test and :test-not argument. 

The keyword :from-end takes a boolean pvar that specifies from which end ofse- 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords: start and :end define a subsequence to be operated on 
in each processor. 

The :key argument specifies a one-argument pvar function that is applied in paral¬ 
lel to each element of sequence-pvar before the comparison with item-pvar is per¬ 
formed. This argument can be used to select a key value from a structure, or to 
manipulate the values being compared. 
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Examples- 

(*defvar vector-pvar (!! #(1 2 3 4 5 6 7))) 

(position!! (!! 4) vector-pvar) <=> (!! 3) 

(position!! (! ! 4) vector-pvar 

-.test ' = !! : key '!-!!) <=> ( ! ! 4) 


Notes- 

Compiler Note: 

The '“Lisp compiler does not compile this operation. 

References- 

See also the functions position-if!! and position-if-not!!. They search 
sequence-pvar for elements that either do or do not pass a supplied test. 

The functions position!!, position-if!!, and position-if-not!! are similar to the 
find!! functions. Here, however, it is the indicies of the matching elements, rather 
than the elements themselves, that are returned. 

These functions are members of a group of similar sequence operators, 
listed below: 

count!! count-if!! count-if-not!! 

find!! find—if!! find-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position-if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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position-if!! [Function] 

Performs a parallel search on a sequence pvar, returning in each processor the posi¬ 
tional index of the first sequence element satisfying the supplied test. 


Syntax- 

position-if!! test sequence-pvar &key :from-end :start :end :key 


Arguments- 

test One-argument pvar predicate. Used to test elements of se¬ 

quence-pvar. 

sequence-pvar Sequence pvar. Contains sequences to be searched. 

:from-end Boolean pvar. Whether to begin search from end of sequence 

in all processors. Defaults to nil. 

: start Integer pvar. Index, zero-based, of sequence element at which 

search starts in each processor. If not specified, search begins 
with first element. 

:end Integer pvar. Index, zero-based, of sequence element at which 

search ends in each processor. If not specified, search contin¬ 
ues to end of sequence. 

:key One-argument pvar accessor function. Applied to each ele¬ 

ment in sequence-pvar before test is performed. 


Returned Value- 

position-pvar Temporary pvar, of same data type as elements of sequence- 
pvar. In each active processor, contains the numeric index of 
the first element of sequence-pvar that satisfied test. Returns 
the value -1 in processors where no such element was found. 
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Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp position-if function. 

In each processor, the function position-if! ! searches sequence-pvar for elements 
that satisfy the supplied test. It returns a pvar containing the index of the first such 
element found in each processor. In any processor failing the search, the returned 
pvar contains -1. A lambda form that takes a single pvar argument and returns a 
boolean pvar result may be supplied as the test argument. 

The keyword :from-end takes a boolean pvar that specifies from which end ofse- 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords : start and :end define a subsequence to be operated on 
in each processor. 

The :key argument specifies a one-argument pvar function that is applied in paral¬ 
lel to each element of sequence-pvar before the comparison with item-pvar is per¬ 
formed. This argument can be used to select a key value from a structure, or to 
manipulate the values being compared. 


Examples- 

(*defvar vector-pvar (!! #(1 2 3 4 5 6 7))) 

(position-if!! (lambda (pvar) (=!! pvar (!! 4))) 
vector-pvar) <=> (!! 3) 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 

count!! count-if!! count-if-not!! 

find!! find—if!! find-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position-if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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position-if-not!! [Function] 

Performs a parallel search on a sequence pvar, returning in each processor the posi¬ 
tional index of the first sequence element failing the supplied test. 


Syntax- 

position-if-not!! test sequence-pvar &key :from-end :start :end :key 


Arguments- 

test One-argument pvar predicate. Used to test elements of se¬ 

quence-pvar. 

sequence-pvar Sequence pvar. Contains sequences to be searched. 

:from-end Boolean pvar. Whether to begin search from end of sequence 

in all processors. Defaults to nil. 

: start Integer pvar. Index, zero-based, of sequence element at which 

search starts in each processor. If not specified, search begins 
with first element. 

:end Integer pvar. Index, zero-based, of sequence element at which 

search ends in each processor. If not specified, search contin¬ 
ues to end of sequence. 

:key One-argument pvar accessor function. Applied to each ele¬ 

ment in sequence-pvar before test is performed. 


Returned Value- 

position-pvar Temporary pvar, of same data type as elements of sequence- 
pvar. In each active processor, contains the numeric index of 
the first element of sequence-pvar that failed test. Returns the 
value -1 in processors where no such element was found. 
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Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp position-if-not 
function. 

In each processor, the function position-if-not!! searches sequence-pvar for ele¬ 
ments that fail the supplied test. It returns a pvar containing the index of the first 
such element found in each processor. In any processor failing the search, the re¬ 
turned pvar contains -1. A lambda form that takes a single pvar argument and 
returns a boolean pvar result may be supplied as the test argument. 

The keyword :from-end takes a boolean pvar that specifies from which end ofse- 
quence-pvar in each processor the operation will take place. 

Arguments to the keywords: start and :end define a subsequence to be operated on 
in each processor. 

The :key argument specifies a one-argument pvar function that is applied in paral¬ 
lel to each element of sequence-pvar before the comparison with item-pvar is per¬ 
formed. This argument can be used to select a key value from a structure, or to 
manipulate the values being compared. 


Examples 


(*defvar vector-pvar (!! #(1 2 3 4 5 6 7))) 

(position-if-not!! (lambda (pvar) (/=!! pvar (!! 4))) 
vector-pvar) <=> (!! 3) 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 

count!! count-if!! count-if-not!! 

find!! find—if! 1 find—if—not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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power-of-two-p [Function] 

Tests whether the supplied integer is an integral power of two. 

Syntax- 

power-of-two-p positive-integer 

Arguments- 

positive-integer Integer. Positive integer to be tested. 

Returned Value- 

power-of-two-p Scalar boolean value. The value t if positive-integer is an inte¬ 
gral power of two, and nil otherwise. 

Side Effects- 

None. 

Description- 

This function returns t if positive-integer is a power of two, otherwise it returns nil. 
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Examples 


Notes 


References- 

See also the related function next-power-of-two->=. 

The power-of-two-p function is most useful in combination with the following VP 
set definition operators: 

def-vp-set create-vp-set let-vp-set 
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ppp [Macro] 

Prints the values of the supplied pvar in neatly formatted style. 

Syntax- : - 

ppp pvar &key :mode :format :per-line :title :start :end 
:ordering :processor-list :print-arrays 
:return-argument-pvar :pretty :stream 


Arguments 

pvar 

:mode 

: format 

:per-line 

:title 

: start 

;end 

: ordering 


Pvar expression. Pvar to be printed. 

Either of :cube or :grid. Determines mode (send/grid) of for¬ 
matted output. Defaults initially to :cube. (See Notes section, 
below.) 

String. Format directive used to print each value. Defaults ini¬ 
tially to “~s ”. 

Integer or nil. Number of values to print on the same line. De¬ 
faults initially to nil, indicating that no line-breaks are to be 
printed. 

String or nil. Text to display as title line, or nil for no title. De¬ 
faults initially to nil. 

Integer or list of integers. Send/grid address of processor at 
which to start formatting values. Defaults initially to 0. 

Integer or list of integers. Send/grid address of processor at 
which to end formatting values. Default value is the current 
value of the global variable *number-of-processors-limit*. 

List of integers or nil. Specifies order in which grid dimensions 
are traversed in formatting of values. This argument is mean¬ 
ingless unless the value of the :mode argument is : grid. De¬ 
faults initially to nil. 
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: processor-list List of integers or nil. Send addresses of processors between 

•.start and :end for which values are formatted. This argument 
is meaningless unless the value of the :mode argument is 
:cube. Defaults initially to nil. 

: print-arrays Scalar boolean. Determines whether arrays are displayed in 
full. Defaults to t. 

:return-argument-pvar 

Scalar boolean. Determines whether ppp returns the 
supplied pvar as its value. Defaults to nil. 

Scalar boolean. Value that Common Lisp global variable 
‘print-pretty* is bound to during printing. Defaults to nil. 

Stream object. Stream to which output is printed. Defaults to 
nil, which directs output to ‘standard-output*. An argument 
of t directs output to *terminal-io*. 


: pretty 

: stream 


Returned Value- 

pvar-or-nil Depending on the value supplied for the :return-argument- 

pvar argument, either the supplied pvar argument or nil. 


Side Effects- 

Prints the selected values of pvar to the stream specified by the : stream argument. 


Description- 

This macro is an alias for the macro pretty-print-pvar, which performs identically. 

The ppp macro prints out the value of pvar in all specified processors, regardless of 
the currently selected set. If ppp accesses a processor that has no defined value for 
pvar, the output produced is not defined. 

The keyword :mode can have the value :cube or :grid; in the latter case the pvar is 
printed out using grid addressing rather than cube addressing. 
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If the :per-line argument is nil, no newlines are ever printed between values; other¬ 
wise, the number of values specified by the :per-line argument are printed on each 
line. 

The keyword :format has as its value a string that controls the printing format for 
each value; its value is used directly by the Common Lisp format function. 

The :ordering keyword argument to ppp takes a list of integers specifying axes. It is 
valid only when used in conjunction with the: grid value of the: mode keyword and 
is most useful for printing a pvar defined in a VP set of more than two dimensions. 
With the :ordering keyword argument to ppp, the user can specify which “slices” of 
the n-dimensional grid are to be displayed. The last two dimensions specified in 
the :ordering list are the two dimensions that are shown as a single slice. 

The keyword argument: pretty controls whether output values are pretty-printed. 
The value of the : pretty argument is bound as the value of the variable 
*print-pretty* for the duration of the call to ppp. 


Examples- 

A sample call to ppp is 

(ppp (self-address!!)) 

0123456789 10 11 12. . . 

The output produced by ppp may be tailored by use of the many keywords. For 
example, 

(ppp (self-address!!) rend 7) 

0 1 2 3 4 5 6 


(ppp (self-address!!) :start 6 rend 24 rper-line 6) 
6 7 8 9 10 11 
12 13 14 15 16 17 
18 19 20 21 22 23 


(ppp (*!! (self-address!!) (self-address!!)) 
:start 1 rend 4 :format "~R " 

:title "The monolith's dimensions are") 
The monolith's dimensions are: one four nine 
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The: processor-list argument may be used to select specific processors to display, 
but only when the printing :mode is '.cube, as it is by default. For example, 

(PPP (-!! (!! 20) (self-address!!)) 

:processor-list '(1 2 3 5 7 11 13 17 19)) 

displays the output 

19 18 17 15 13 9 7 3 1 

The :grid option to the :mode keyword causes the output of ppp to be displayed in 
grid-address format. For example, assuming a two-dimensional grid, 

(ppp (self-address!!) :mode :grid :end '(4 4)) 

displays output similar to 

0 8 16 24 

1 9 17 25 

2 10 18 26 
3 11 19 27 

The: ordering argument may be used to specify the order in which grid dimensions 
are displayed. For example, 

(ppp (self-address!!) :mode :grid :end '(4 4) 

:ordering '(1 0)) 


displays output similar to 

0 12 3 
8 9 10 11 
16 17 18 19 
24 25 26 27 


The keyword argument: pretty can be used to cause the output of some pvar values 
to be displayed in a neater format. Calling ppp on a structure pvar, for example, 
yields output such as the following: 


#S(PERSON :NAME 0 :AGE 0 :SEX NIL) #S(PERSON :NAME 0 :AGE 0 
:SEX NIL) #S(PERSON :NAME 0 :AGE 0 :SEX NIL) 
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If the keyword argument: pretty is given the value t, this structure is printed as: 


#S(PERSON 

: NAME 

0 

: AGE 

0 


: SEX 

NIL) 


#S(PERSON 

: NAME 

0 

: AGE 

0 


: SEX 

NIL) 


#S(PERSON 

: NAME 

0 

: AGE 

0 


: SEX 

NIL) 



Notes- 

There are global variables that specify the defaults for each of the keyword argu¬ 
ments except: 

:pretty -.print-arrays :return-argument-pvar 

: stream 

See Chapter 2, “*Lisp Global Variables,” in Part I of this Dictionary for a list of 
these variables and the default values to which they are initially bound. 

Simulator Note: 

The number of processors defined by default in the *Lisp simulator is very 
much lower than the number of processors generally available using CM hard¬ 
ware. Therefore, while using the *Lisp simulator, if ppp is called with no 
keyword arguments, as in 

(ppp data-pvar) 

then only a few values will be displayed. The same call to ppp executed with CM 
hardware attached can potentially display thousands or millions of values. 
When using CM hardware, it is prudent to use the: start and :end keywords (or 
the global variables controlling their defaults) to limit the number of values 
displayed. 
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References-— 

See also these related pvar pretty-printing operations: 

pppi! 

ppp-address-object ppp-css 

pppdbg ppp-struct 

pretty-print-pvar pretty-print-pvar-in-currently-selected-set 
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ppp!! [Macro] 

Prints the values of the supplied pvar in neatly formatted style, and returns the 
supplied pvar as its value. 

Syntax- 

pppl! pvar &rest keyword-args 

Arguments- 

pvar 

keyword-args 

Returned Value 

pvar The supplied pvar argument is returned. 

Side Effects- 

Prints selected values of pvar to the stream specified by the : stream argument. 

Description- 

The function ppp! ! is identical to ppp except that it returns its pvar argument. The 
argument pvar may be any pvar. The keyword-args are identical to those for ppp, 
with the exception of :return-argument-pvar. 


Pvar expression. Pvar to be printed and returned. 

Keyword arguments. Accepts same keyword arguments as 

PPP- 
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Examples 


Notes- 

There are global variables that specify the defaults for each of the keyword argu¬ 
ments. See Chapter 2, “*Lisp Global Variables” in Part I of this Dictionary for a list 
of these variables. 


References 


See also these related pvar pretty-printing operations: 


PPP 

ppp-address-object 

pppdbg 

pretty-print-pvar 


ppp-css 

ppp-struct 

pretty-print-pvar-in-currently-selected-set 
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ppp-addreSS-Object [Function] 

Prints the values of the supplied address-object pvar in neatly formatted style. 


Syntax- 

ppp-address-object address-object-pvar &key :title rstart :end :mode 


Arguments- 

address-object-pvar 

Address-object pvar. Pvar to be printed. 

:mode Either of :cube or : grid. Determines mode (send/grid) of for¬ 

matted output. 

:title String or nil. Text to display as title line, or nil for no title. 

: start Integer. Send address of processor at which to start formatting 

values. 

:end Integer. Send address of processor at which to end formatting 

values. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Prints selected values of address-object-pvar to * standard-output* stream. 

Description- 

This function is a specialized pretty-printer for address-object pvars. 
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Examples 


Notes- 

There are global variables that specify the defaults for each of the keyword argu¬ 
ments. See Chapter 2, “*Lisp Global Variables” in Part I of this Dictionary for a list 
of these variables. 


References- 

See also these related pvar pretty-printing operations: 

ppp ppp!! 

ppp-css 

pppdbg ppp-struct 

pretty-print-pvar pretty-print-pvar-in-currently-selected-set 
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ppp-CSS [Macro] 

Prints out the send address, and the value of the supplied pvar, for each processor of 
the currently selected set 

Syntax- 

ppp-css pvar &key rformat :start :end :title :mode 

Arguments 

pvar 

: format 
: start 

:end 

:title 
:mode 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

Prints send addresses and values from pvar to the *standard-output* stream. 

Description- 

This macro is an alias for pretty-print-pvar-in-currently-selected-set. 


Pvar expression. Pvar from which values are printed. 

String. Format directive used to print each value. 

Integer. Send address of processor at which to start formatting 
values. 

Integer. Send address of processor at which to end formatting 
values. 

String or nil. Text to display as title line, or nil for no title. 

Either of : cube or : grid. Determines mode (send/NEWS) of for¬ 
matted output. 
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Examples 


Notes- 

There are global variables that specify the defaults for each of the keyword argu¬ 
ments. See Chapter 2, “*Lisp Global Variables” in Part I of this Dictionary for a list 
of these variables. 


References- 

See also these related pvar pretty-printing operations: 

PPP PPP” 

ppp-address-object 

pppdbg ppp-struct 

pretty-print-pvar pretty-print-pvar-in-currently-selected-set 
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pppdbg [Macro] 

Prints the values of the supplied pvar in neatly formatted style, displaying the form that 
is evaluated to provide the pvar as a title. 


Syntax- 

pppdbg pvar &rest keyword-args 


Arguments- 

pvar Pvar expression. Pvar to be printed. 

keyword-args Keyword arguments. Accepts same keyword arguments as 

PPP- 


Returned Value- 

pvar-or-nil Depending on the value supplied for the :return-argument- 

pvar argument, either the supplied pvar argument or nil. 


Side Effects- 

Prints selected values of pvar to the stream specified by the : stream argument. 


Description- 

This macro is equivalent to ppp, except that the : title keyword argument defaults, 
not to nil (no title), but to the original form supplied as the pvar argument for 
pppdbg. The argument pvar may be any pvar. The keyword-args are identical to 
those for ppp. 
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Examples- 

For example, the expression 

(pppdbg (self-address!!) rend 10) 
displays the following: 

(SELF-ADDRESS!!): 0123456789 


Notes- 

There are global variables that specify the defaults for each of the keyword argu¬ 
ments. See Chapter 2, “*Lisp Global Variables” in Part I of this Dictionary for a list 
of these variables. 


References- 

See also these related pvar pretty-printing operations: 

PPP PPP” 

ppp-address-object ppp-css 

ppp-struct 

pretty-print-pvar pretty-print-pvar-in-currently-selected-set 


732 




*Lisp Dictionary 


ppp-struct 


PPp-StrUCt [Function] 

Prints the contents of the supplied structure pvar in a readable format. 


Arguments- 

ppp-struct pvar per-line &key :start :end :print-array 

:stream :width :title 

pvar Structure pvar. Pvar to print in readable format. 

per-line Positive integer. Number of values to display per line. 

: start Integer. Send address of processor at which printing starts. De¬ 

faults to 0. 

:end Integer. Send address of processor at which to printing ends. 

Defaults to *number-of-processors-limit*. 

:print-array Boolean. Determines whether arrays are printed out in full. 

Defaults to t. 

: stream Stream object or t. If supplied, output is written to the specified 

stream. Defaults to t, sending output to 'standard-output*. 

: width Integer. Width, in characters, of each value displayed. Defaults 

to 8 characters. 

:title String or nil. Text to display as title line, or nil for no title. De¬ 

faults to name of pvar’s structure type. 


Returned Value- 

nil Evaluated for side-effect only. 


Side Effects- 

The contents of pvar from processor start up to processor end is written to stream in 
a readable format. 
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Description- 

The function ppp-struct attempts to print out the structure pvar pvar in readable 
format, with processor values for each slot being shown left to right, one line per 
slot. The number of values displayed per line is determined by per-line. 

The keyword arguments : start, :end,:print-array, and : stream control the amount, 
format, and destination of the output exactly as with ppp. 

The argument rwidth determines the printed width of each slot value, and defaults 
to 8 characters. 

The argument: title defaults to t, which specifies that the title printed out is the 
name of the * def struct of which pvar is an instance of. If nil, no title is printed out. 
If it is a string, then that string is used as the title. 


Examples 


(*defstruct person 

(ssn 0 :type (unsigned-byte 32)) 
(age 0 :type (unsigned-byte 16)) 
(height 0.0 :type single-float) 
(weight 0.0 :type single-float) 

) 


(ppp-struct a-person 8 :end 16 :width 10) 


*DEFSTRUCT PERSON 


SSN: 

219101296 

545417079 

833166928 

508389095 

945762998 

685245194 

687147484 442455228 



AGE: 

43 


76 

9 

96 

63 

31 


59 

82 




HEIGHT: 

0 . 

7566829 

6.0384245 

6.8458276 

2.9526687 

6.9201202 

2.5360777 

0.65423644 0.16378379 



WEIGHT: 

52 

.873016 

11.53174 

29.510529 

223.5896 

244.65019 


130.44492 24.180532 214.51915 
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SSN: 604959766 822929695 445946453 856011938 

724449217 967664808 640359065 

AGE: 27 28 88 68 

66 61 31 

HEIGHT: 2.01059 5.2301087 6.1360407 1.8808416 

5.686286 5.1784062 4.504147 

WEIGHT: 82.76129 200.76877 165.2837 48.37853 

84.00104 16.700924 232.88974 


684206262 

98 

6.9195743 

154.92798 


NIL 


Notes- 

There are global variables that specify the defaults for each of the keyword argu¬ 
ments except: 

■ : print-array 

■ : stream 

■ :width 

See Chapter 2, “*Lisp Global Variables” in Part I of this Dictionary for a list of 
these variables. 


References- 

See also these related pvar pretty-printing operations: 

PPP PPP!! 

ppp-address-object ppp-css 

pppdbg 

pretty-print-pvar pretty-print-pvar-in-currently-selected-set 
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pref [Macro] 

Retrieves the value of the supplied pvar in a single processor. 

Syntax- 

pref pvar-expression send-address &key :vp-set 

Arguments- 

pvar-expression Pvar or pvar expression. Pvar from which value is accessed. 

send-address Integer or address object. Send address of processor from 
which value is accessed. 

:vp-set VP set object. VP set to which the result of pvar-expression be¬ 

longs. Defaults to the value of *current-vp-set*. 

Returned Value- 

scalar-value Value obtained by evaluating pvar-expression with the single 

processor specified by send-address selected. 

Side Effects- 

None. 


Description- 

This macro returns, as a Lisp value, the value of pvar-expression in the processor 
specified by send-address. The pvar returned by pvar-expression may be any type of 
pvar, and may belong to any VP set. 

The :vp-set argument determines the VP set in which the supplied pvar-expression 
is evaluated. If a :vp-set argument is not specified, pvar-expression is assumed to 
belong to the current VP set. It is only necessary to supply a value for the :vp-set 
argument if pvar-expression is an expression that must be evaluated in a VP set 
other than the current VP set. 
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Examples- 

The expression 
(pref foo 17) 

returns the value of pvar foo in processor 17. 

The macro *setf may be applied to pref to store a value into a single processor of a 
pvar. For example, the expression 

(*setf (pref foo 17) (* 19 99)) 

sets the value of pvar foo in processor 17 to 1881. 

The send-address argument may reference any processor; it is not limited to 
processors in the currently selected set. The pref macro may be used to access any 
processor, whether or not that processor is currently active, in which the 
pvar-expression contains valid data. 

For example, the result returned by the expression 
(*all 

(*let ((x (self-address!!))) 

(*when (<!! (self-address!!) (!! 10)) 

(pref x 30)))) 

is defined, even though the call to *when deselects processor 30. The contents of 
the local pvar x is set in all processors prior to the call to *when, so that when pref is 
called to access the value of x in processor 30, that value is defined. 

The result of the following similar expression is not defined, however. 

(*all 

(*when (<!! (self-address!!) (!! 10)) 

(*let ((x (self-address!!))) 

(pref x 30)))) 

This example is in error, for the contents of x are determined after the currently 
selected set has been restricted, excluding processor 30. The local pvar x therefore 
has no defined value in that processor. The value returned by this example is unde¬ 
fined. 
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The pref function may be used to read values using grid addresses in either of two 
ways. One way is to call the function cube-f rom-grid-address (or cube-f rom-vp- 
grid-address), as in 

(pref data-pvar (cube-from-grid-address 10 5 2 4)) 

(assuming that data-pvar belongs to a four-dimensional VP set). The other is to 
supply an address object by calling the function grid, as in 

(pref data-pvar (grid 10 5 2 4)) 


Notes- 

Performance Note: 

To read a single array element from an array pvar there are two possibilities. 
The first is to copy the entire array containing the element from the CM to the 
front end, and then to reference the element itself. The second and much faster 
method is to perform a parallel array reference on the CM, and then to select a 
single value from the resulting pvar. 

As a specific example, assume an array pvar has been defined by 
(*defvar my-array-pvar 

(vector!! (self-address!!) (-!! (self-address!!)))) 

(pref my-array-pvar 3) 

#(3 -3) 

The first method copies an entire array from my-array-pvar with pref, and 
then uses the Common Lisp aref operator to reference a single array element 
on the front end. For example, 

(aref (pref my-array-pvar 3) 1) 

-3 

The second method performs a parallel array reference on the CM with aref!!, 
and then uses pref to access a single value from the resulting pvar. 

(pref (aref!! my-array-pvar (!! 1)) 3) 

-3 
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This second method is much faster for array pvars containing large arrays 
because less data is transmitted between the CM and the front end. Even for 
expressions involving small arrays, the second method is more efficient 
because the *Lisp compiler is able to recogize and compile expressions of this 
type. 

Of course, this same principle applies to reading data from a single slot of a 
structure pvar. It is in general more efficient to perform a parallel reference on 
the CM than it is to copy an entire array or structure from the CM to the front 
end and performing a serial reference on the front end. 


References-- 

See also the !! operator, which takes a single value and broadcasts it to all 
processors. 

See also the following four operations that move more than one element at a time 
between the front end and the CM: 

array-to-pvar array-to-pvar-grid 

pvar-to-array pvar-to-array-grid 

See also the related operations: 

pref!! *pset *set *setf 
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pref!! [Macro] 

Performs a parallel retrieval of values from the supplied pvar. 

Syntax- 

pref!! pvar-expression send-address-pvar &key :collision-mode :vp-set 

Arguments- 

pvar-expression Pvar expression. Pvar from which values will be retrieved. 

send-address-pvar Pvar containing send addresses or address objects. Address of 
processor from which the value of pvar-expression is retrieved. 

:collision-mode A symbol. Must be one of :collisions-allowed, :no-collisions, 
:many-collisions, or nil. Specifies method used to resolve 
collisions. Defaults to nil. 

:vp-set VP set object. VP set to which the pvar returned by pvar-expres¬ 

sion belongs. Defaults to VP set of pvar-expression. If pvar-ex¬ 
pression is an expression rather than a pvar, this argument 
defaults to *current-vp-set*. 

Returned Value- 

pref-pvar Temporary pvar. In each active processor, contains the value of 

pvar-expression in the processor whose address is the corre¬ 
sponding value of send-address-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

The pref !! macro is an interprocessor and inter-VP set communication operation. 
It returns a pvar containing in each active processor the value of pvar-expression in 
the processor specified by send-address-pvar. 

Each active processor retrieves a value from the pvar returned by pvar-expression. 
Specifically, each processor retrieves the value of pvar-expression in the processor 
specified by the value of send-address-pvar. 

The processors from which these values are being retrieved need not be in the cur¬ 
rently selected set. Also, pvar-expression need not be in the current VP set. The 
pref!! operation allows data to be retrieved from non-active processors and from 
pvars in VP sets other than the current one. 

The keyword argument: collision-mode determines the communication method 
used when there are collisions. A collision occurs when a single value of pvar-ex¬ 
pression is accessed by more than one processor, i.e., when the value of 
send-address-pvar is the same in two or more active processors. The Connection 
Machine arranges that all processors involved in a collision get the same value, but 
depending on the number of collisions that occur, one of a number of strategies 
may be used to provide efficient communication. 

The : collision-mode argument has four legal values: 

■ :no-collisions 

This option asserts that no two processors will attempt to reference the 
same value. If two processors do attempt to access the same value, the re¬ 
sult is undefined. The : no-collisions option is significantly faster than any 
of the options that allow collisions, with the exception of the nil option. 

■ :coilisions-allowed 

This option asserts that collisions are allowed, but that relatively few colli¬ 
sions will actually occur. The time required to complete the pref !! opera¬ 
tion is proportional to the maximum number of processors involved in a 
collision. 

■ :many-collisions 

This option asserts that many collisions will occur, and is especially useful 
when large numbers of processors are accessing the same value. This op¬ 
tion is slower than the preceding two, but the algorithm used ensures that 
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the pref!! operation takes constant time regardless of the number of colli¬ 
sions. 

■ nil 

This option is the default, and asserts that any number of collisions may 
occur. While this option is faster than either :collisions-allowed or 
: many-collisions, and can even be faster than: no-collisions in some cases, 
it uses significantly more memory. If this option requires more memory 
than is currently available, the :many-collisions option will automatically 
be used instead. 

The :collision-mode argument allows *Lisp to optimize communication in cases 
where each value of send-address-pvar is unique (i.e., : no-collisions), or when 
many values of send-address-pvar are the same (i.e.,: many-collisions). Note that 
this argument represents an assertion by the user about what can be expected to 
happen. If this assertion is violated, the pref !! operation will run much more slowly. 
In the case of the : no-collisions option, some data can be lost, as well. 

The :vp-set argument determines the VP set in which the supplied pvar-expression 
is evaluated. It is only necessary to supply a value for the: vp-set argument if pvar- 
expression is an expression that must be evaluated in a VP set other than the current 
VP set. 

The send-address-pvar argument specifies the send addresses of processors either 
in the current VP set or another VP set. If pvar-expression is a symbol bound to a 
pvar and no : vp-set argument is specified, the values of send-address-pvar are in¬ 
terpreted relative to the VP set to which pvar-expression belongs. If pvar-expression 
is an expression and no : vp-set argument is specified, the values of send-address-, 
pvar are interpreted relative to the *current-vp-set*. If pvar-expression is an 
expression and a: vp-set argument is specifed, the values of send-address-pvar are 
interpreted relative to the :vp-set argument. 

The actual evaluation of pvar-expression is performed only in those processors 
from which values are being retrieved. Both the send-address-pvar and : vp-set ar¬ 
guments are used to determine the set of processors in which pvar-expression is 
evaluated: 

■ If pvar-expression is a symbol bound to a pvar, then pvar-expression is 
evaluated in the set of processors specified by send-address-pvar in the VP 
set to which pvar-expression belongs. 
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■ If pvar-expression is an expression and no :vp-set argument is provided, 
then pvar-expression is evaluated in the set of processors specified by 
send-address-pvar in the current VP set. 

■ If pvar-expression is an expression and a :vp-set argument is specified, 
then pvar-expression is evaluated in the set of processors specified by 
send-address-pvar in the VP set specified by the : vp-set argument. 

Examples of these three cases are shown below. 


Examples- 

Here is a sample call to pref!!: 

(*defvar pvar-a (random!! (!! 10))) 

(*defvar pvar-b) 

(*set pvar-b (pref!! pvar-a (self-address!!))) 

The value of pvar-a in each processor is copied and returned by pref! !, and stored 
in pvar-b by *set. In this example, no interprocessor communication takes place; 
each processor is simply getting data from itself. 

More interesting uses of pref!! involve exchanging values between processors. For 
example, the expression 

(*set backwards-pvar 

(pref!! pvar (-!! (!! (1- *number-of-processors-limit*)) 

(self-address!!)))) 

stores the values of pvar into backwards-pvar in reverse order of send addresses. 
The expression 

(*set pvar-a 

(pref!! pvar-a (mod!! (1-!! (self-address!!)) 

(!! *number-of-processors-limit*)))) 

shifts the value of pvar-a in each processor to the processor with the next higher 
send address (with wraparound). 
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This example demonstrates that pvar-expression is evaluated only in the processors 
from which values are being retrieved: 

(♦all 

(♦when (not!! (=!! (self-address!!) 

(!! (1- ♦number-of-processors-limit*)))) 
(PPP (pref!! (/!! (!! 1.0) (self-address!!)) 

(1+!! (self-address!!))) 

:end 4))) 

1.0 0.5 0.3333334 0.25 

Each processor retrieves data from its successor in send address order. (The call to 
*when excludes the processor with the highest address.) If the expression 

(/!! (!! 1.0) (self-address!!)) 

was evaluated in the currently selected set of processors, including processor 0, 
then a division by zero would occur. However, no processor retrieves a value from 
processor 0 in the above example, so processor 0 does not evaluate the division 
form in the call to pref!!, and no division by zero occurs. Note also that a value is 
retrieved from the processor with the highest address, even though that processor 
is not currently active. 

The next example demonstrates that pvar-expression is evaluated in the VP set 
specified by the :vp-set argument, and only in the processors in that VP set from 
which values are retrieved (in this case a single processor). 

(def-vp-set fred '(256 256)) 

(♦defvar fred-pvar (self-address-grid!! (!! 0)) 
n Fred X coordinate” fred) 

(def-vp-set barney "(65536)) 

(*with-vp-set barney 
(PPP 

(pref!! 

(progn 

(format t "~%The current vp set is ~S” 

♦current-vp-set*) 

(format t ”~%The number of active processors is ~S” 


(♦sum (! 

! 1))) 

fred-pvar) 


(grid!! (!! 25) ( ! 

! 25)) 
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:vp-set fred) 

:end 5)) 

This example produces the following output: 

The current vp set is #<VP-SET Name: FRED, Dimensions . . . > 
The number of active processors is 1 
25 25 25 25 25 

The pref! ! operation can also be used to transfer values between different VP sets, 
as in the following example. 

(♦proclaim '(type (pvar (unsigned-byte 4)) 

matrix diagonal-elements)) 

(def-vp-set diagonal-vp-set '(8192) 

:*defvars ((diagonal-elements (!! 0)))) 

(def-vp-set matrix-vp-set '(128 128) 

:*defvars ((matrix (random!! (!! 10))))) 

These forms define two VP sets, diagonal-vp-set and matrix-vp-set, with one and 
two dimensions respectively. Two pvars are also defined, one associated with each 
VP set, that have the following initial values: 

(ppp matrix :mode :grid :end '(5 5)) 

DIMENSION 0 (X) -> 

5 6 3 5 6 

4 9 4 5 6 

3 9 15 2 

2 6 2 3 9 

4 0 9 3 4 


(ppp diagonal-elements :end 5) 
0 0 0 0 0 
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The following function uses pref !! to copy values from matrix that are stored along 
the diagonal of the matrix-vp-set grid into the diagonal-elements pvar. 

(defun retrieve-diagonal-elements () 

(*with-vp-set diagonal-vp-set ;;; VP set of dest-pvar 
(*when (<!! (self-address!!) (!! 128)) 

(*set diagonal-elements 

(pref!! matrix-vp-set 

(cube-from-vp-grid-address!! 

; Treat pair of send addresses from one-d 
; as grid address in two-d, and convert 
; to corresponding send address in two-d 
(self-address!!) 

(self-address!!)) 

:vp-set matrix-vp-set ;; VP set of dest-pvar 

))))) 

Following a call to retrieve-diagonal-elements, the matrix and diagonal-elements 
pvars display as: 

(ppp matrix :mode :grid :end '(5 5)) 

DIMENSION 0 (X) -> 

5 6 3 5 6 
4 9 4 5 6 

3 9 15 2 
2 6 2 3 9 

4 0 9 3 4 


(ppp diagonal-elements :end 5) 

5 9 13 4 

Note the use of cube-from-vp-grid-address!! to determine the send addresses of 
the diagonal elements in matrix-vp-set. The send address of each element of the 
diagonal-elements pvar is used twice to form a grid address along the diagonal 
of the matrix pvar. This grid address is then converted by 
cube-from-vp-grid-address!! into the appropriate send address within 
matrix-vp-set. 


747 





pref!! 


*Lisp Dictionary 


Another way of converting grid addresses to send addresses within a pref!! form is 
the use the grid!! function. For instance, the above call to pref!! could have been 
written as 

(pref!! matrix (grid!! (self-address!!) (self-address!!))) 

See the definition of grid!!, and Section 6.5, “Address Objects” of the *Lisp 
Reference Supplement, Version 5.0, for more information. 


Notes- 

Usage Note: 

The default value (nil) of : collision-mode invokes the Paris instruction 
cm:get-IL, which uses the CM-2 backward routing hardware. As the number of 
collisions increases, this tends to be faster than :collisions-allowed and 
:many-collisions, but it can require much more temporary memory. 

Performance Note: 

A call to pref! ! with no collisions is implemented using two calls to * pset: one to 
send the address of the processor requesting the data to the processor from 
which the data is to be retrieved, and another to send the data requested back 
to the requesting processor. 

It is often possible to rewrite an algorithm that uses pref!! (in which data is 
retrieved) into an algorithm using *pset (in which data is sent, rather than re¬ 
trieved), halving the communications time required. 

For example 

(♦when (<!! (self-address!!) (!! 100)) 

(♦set dest (pref!! source 

(+!! (self-address!!) (!! 100))))) 

could be rewritten as 

(*when (and!! (<=!! (!! 100) (self-address!!)) 

(<!! (self-address!!) (!! 200))) 

(*pset source dest (-!! (self-address!!) (!! 100)))) 
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Style Note: 

The pref!! macro may be used with *setf. However, a call to *setf of the form 
(*setf (pref!! dest-pvar address-pvar) source-pvar) 
is equivalent to a call to *pset of the form 

(*pset :no-collisions source-pvar dest-pvar address-pvar) 
Calling *pset directly in this case is preferable as being more readable. 


References- 

See also the macro *pset, which performs a parallel store operation. 

See also these related NEWS communication operators: 

"news news!! news-border!! 

* news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 
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pretty-print-pvar [Macro] 

Prints the values of the supplied pvar in neatly formatted style. 

Syntax- 

pretty-print-pvar pvar &key -.mode iformat :per-line -.title -.start :end 

:ordering :processor-list :print-arrays 
: return-argument-pvar : pretty :stream 


Arguments 

pvar 

:mode 

iformat 

:per-line 

ititle 

: start 

:end 

:ordering 


Pvar expression. Pvar to be printed. 

Either of icube or igrid. Determines mode (send/grid) of for¬ 
matted output. Defaults initially to icube. (See Notes section, 
below.) 

String. Format directive used to print each value. Defaults ini¬ 
tially to “'S ”. 

Integer or nil. Number of values to print on the same line. De¬ 
faults initially to nil, indicating that no line-breaks are to be 
printed. 

String or nil. Text to display as title line, or nil for no title. De¬ 
faults initially to nil. 

Integer or list of integers. Send/grid address of processor at 
which to start formatting values. Defaults initially to 0. 

Integer or list of integers. Send/grid address of processor at 
which to end formatting values. Default value is the current 
value of the global variable *number-of-processors-limit*. 

List of integers or nil. Specifies order in which grid dimensions 
are traversed in formatting of values. This argument is mean¬ 
ingless unless the value of the imode argument is igrid. De¬ 
faults initially to nil. 
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’.processor-list List of integers or nil. Send addresses of processors between 
: start and :end for which values are formatted. This argument 
is meaningless unless the value of the :mode argument is 
:cube. Defaults initially to nil. 

•.print-arrays Scalar boolean. Determines whether arrays are displayed in 
full. Defaults to t. 

:return-argument-pvar 

Scalar boolean. Determines whether pretty-print-pvar returns 
the supplied pvar as its value. Defaults to nil. 

Scalar boolean. Value that Common Lisp global variable 
* print-pretty* is bound to during printing. Defaults to nil. 

Stream object. Stream to which output is printed. Defaults to 
nil, which directs output to ‘standard-output*. An argument 
of t directs output to *terminal-io*. 


.‘pretty 

: stream 


Returned Value- 

pvar-or-nil Depending on the value supplied for the :return-argument- 

pvar argument, either the supplied pvar argument or nil. 


Side Effects- 

Prints the selected values of pvar to the stream specified by the : stream argument. 


Description- 

This macro has an alias ppp, which operates identically. See the definition of ppp 
for more information about both of these macros. 


Examples- 

A sample call to pretty-print-pvar is 

(pretty-print-pvar (self-address!!)) 
0123456789 10 11 12. . . 
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The output produced by pretty-print-pvar may be tailored by use of the many key¬ 
words. For examples of the use of the keyword arguments, see the definition of the 
macro ppp. 


Notes- 

There are global variables that specify the defaults for each of the keyword argu¬ 
ments except: 

:pretty :print-arrays :return-argument-pvar 

: stream 

See Chapter 2, “*Lisp Global Variables” for a list of these variables, and the de¬ 
fault values to which they are initially bound. 


References- 

This macro has an alias, ppp. 

See also these related pvar pretty-printing operations: 

ppp!! 

ppp-address-object ppp-css 

pppdbg ppp-struct 

pretty-print-pvar-in-currently-selected-set 
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p retty- print- p var- [Macro] 

in-currently-selected-set 

Prints out the send address and value of the supplied pvar for all processors in the 
currently selected set. 


Syntax- 

pretty-print-pvar-in-currently-selected-set pvar 
&key ‘.format :start :end :title :mode 


Arguments- 

pvar Pvar expression. Pvar from which values are printed. 

: format String. Format directive used to print each value. 

: start Integer. Send address of processor at which to start formatting 

values. 

:end Integer. Send address of processor at which to end formatting 

values. 

:title String or nil. Text to display as title line, or nil for no title. 

:mode Either of :cube or :grid. Determines mode (send/grid) of for¬ 

matted output. 

Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Prints send addresses and values from pvar to the ’standard-output* stream. 
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Description- 

This function prints out the the cube address and value of pvar for all processors in 
the currently selected set. 

Examples- 

Notes- 

There are global defaults for each of the keyword arguments. 

See Chapter 2, “*Lisp Global Variables” for a list of these variables. 

References- 

This macro has an alias, ppp-css. 

See also these related pvar pretty-printing operations: 

PPP PPP!! 

ppp-address-object 

pppdbg ppp-struct 

pretty-print-pvar 
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*processorwise [* Defun] 

Converts a sideways (slicewise) array to the normal, processorwise orientation. 

Syntax- 

* processorwise array-pvar 

Arguments- 

array-pvar Array pvar. Sideways (slicewise) array pvar to be converted. 

Returned Value- 

t Evaluated for side effect only. 

Side Effects- 

Converts array-pvar from sideways to normal, processorwise orientation. 

Description- 

Converts a sideways (slicewise) array to a normal, processorwise orientation. 

The array-pvar parameter must be a sideways (slicewise) array, otherwise an error 
is signaled. 
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Examples 


Notes- 

The function "processorwise is equivalent to a call to *sideways-array with an 
array argument that is in sideways (slicewise) orientation. 

There are some important restrictions on the size of arrays passed as arguments to 

*processorwise. 

The array-pvar argument must be an array pvar that contains elements whose 
lengths are powers of 2 or multiples of 32. Further, the total number of bits the 
array occupies in CM memory must be divisible by 32. This number can be deter¬ 
mined either by (pvar-length array-pvar) or by multiplying the total number of 
elements in the array by the size of an individual element. 

The *processorwise function is most efficient when the array elements of array- 
pvar are each 32 bits long. 


References- 

See also the functions * sideways-array, sideways-array-p, and *slicewise. 


V 
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'proclaim [Macro] 

Records a global declaration about *Lisp variables and functions. Also provides the 
*Lisp compiler with information about Common Lisp variables. 


Syntax- 

* proclaim declaration 


Arguments- 

declaration *Lisp declaration form. Proclamation to be recorded. This 

argument is evaluated, so declaration forms must be quoted. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Records declaration as a global declaration about *Lisp variables and functions. 


Description- 

The *Lisp version of the Common Lisp proclaim function. It is used to make global 
declarations, including the data types of global pvar variables and user-defined 
functions. 
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Examples- 

The "proclaim macro is commonly used in five ways: 

S! To provide type declarations for permanent pvars defined by "defvar. 

(♦proclaim '(type (pvar single-float) my-float-pvar)) 
(♦defvar my-float-pvar) 


(♦proclaim 

'(type (vector-pvar (array (unsigned-byte 32) (4 4)) 3) 
my-nested-arrayl my-nested-array2)) 

(♦defvar my-nested-arrayl) 

(♦defvar my-nested-array2) 

H To provide function declarations so that the *Lisp Compiler has 
information regarding the returned value of user-defined *Lisp functions. 

For example, 

(♦proclaim 

'(ftype (function (single-float-pvar single-float-pvar) 
single-float-pvar) 
hypotenuse!!)) 

informs the *Lisp compiler that the hypotenuse! ! function takes two single 
float pvars as arguments and returns a single float pvar as a result. 

The expression 

(♦proclaim '(ftype (function (forest t) 

(pvar boolean) 

my-and!!)) 

informs the *Lisp compiler that the my-and!! function takes any number 
of arguments of any type, and returns a boolean pvar. 

Currently, the *Lisp compiler does not use the information about 
arguments provided in function or ftype "proclaim forms. The declaration 
for each argument in these forms may be completely specified for 
documentation purposes, or may be specified simply as t. However, the 
number of argument declarations provided must match the number of ar¬ 
guments accepted by the function. 
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n To provide the *Lisp compiler with information about scalar variables 
used in pvar expressions. Note that ‘proclaim is used instead of proclaim, 
so that the *Lisp compiler will have access to the declarations. 

(♦proclaim '(type double-float two-pi)) 

(defparameter two-pi (* pi 2.0)) 

(♦proclaim '(type fixnum x-dimension y-dimension)) 

(defvar x-dimension 3) 

(defvar y-dimension 4) 

ll To define or change the compiler settings for the *Lisp compiler. 

For example, 

(♦proclaim '(*optimize (safety 3))) 

informs the *Lisp compiler that full safety should be enabled globally. For 
more information about the *Lisp compiler and the many compiler set¬ 
tings available, see the *Lisp Compiler Guide, Version 5.0. 

li To inform the Lisp compiler that a symbol will later be defined with * defun, 
and will therefore be a macro rather than a function. 

For example, 

(♦proclaim '(*defun foo)) 

(defun bar (x) (foo x)) 

(*defun foo (x) (*sum x)) 

Without the call to ‘proclaim, when bar is compiled the call to foo is treated 
as a function call. When foo is defined with ‘defun, it is actually defined as 
a macro, so that the call to foo within bar will not execute properly. Declar¬ 
ing that foo will be defined by * defun prior to the definition of any function 
that calls foo allows Lisp to compile these functions properly. 


761 



* proclaim 


*Lisp Dictionary 


Notes- 

Syntax Notes: 

The declaration argument of * proclaim must be quoted to prevent evaluation, 
just as in Common Lisp the declaration argument to proclaim must be quoted. 

Also, nearly all calls to ’proclaim end with a double parentheses, as the above 
examples show. It is a good rule of thumb to recheck any ’proclaim form 
ending with a single parenthesis or with more than two parentheses, for it may 
contain an error. Note the exception given by the fourth example above. The 
use of ’proclaim to declare the *Lisp compiler safety level ends in three 
parentheses, but is nevertheless correct. 

Compiler Note: 

The use of the Common Lisp proclaim operator to inform the *Lisp compiler 
of type information is obsolete and no longer supported. 


References- 

See also the related *Lisp declaration operators: 

’locally unproclaim 

See also the related type translation function taken-as!!. 
See also the related type coercion function coerce!!. 
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*pset 

[Macro] 

Copies values from the source pvar into the destination pvar. This operation may be 
used to transfer values between processors in the same VP set and between processors 
in different VP sets. 

Syntax- 



*pset combine-method source-pvar destination-pvar dest-address-pvar 

&key :notify-pvar :vp-set :collision-mode 

Arguments- 



combine-method 

Keyword. Specifies the method used to combine multiple val¬ 
ues sent to the same processor. Must be one of: : default, 
:no-collisions, :overwrite, :or, :and, :logior, :logand, :add, 
:max, :min 

source-pvar 

Pvar from which values are copied. The value in each active 
processor must be of a data type that can legally be stored in 
destination-pvar. The source-pvar argument must belong to the 
current VP set. 

destination-pvar 

Pvar into which values are copied. May belong to any VP set. 

dest-address-pvar 

Pvar containing send addresses or address objects. Addresses 
must be valid for the VP set to which destination-pvar belongs. 

:notify-pvar 

Boolean pvar used to indicate in which processors destination- 
pvar is altered. If supplied, it is set to t in those processors that 
receive a value. Must belong to the same VP set as destination- 
pvar. 

:vp-set 

VP set object. If supplied, it must be the VP set to which desti¬ 
nation-pvar belongs. Used for optimization purposes only. 

:collision-mode 

The :collision-mode keyword argument is superfluous, and is 
retained for compatibility purposes. 
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Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

In each processor specified by dest-address-pvar, destination-pvar is overwritten 
with either a single source-pvar value or a combination of source-pvar values. 

If notijy-pvar is supplied, it is set to t in each processor in which destination-pvar 
received a value; elsewhere it is unaffected. 


Description- 

The *pset macro is an interprocessor and inter- VP set communication operation. 
It copies values from one pvar to another. Source values from one processor may 
be copied to a different processor. Also, source-pvar and destination-pvar may be¬ 
long to different VP sets. 

Using a mailbox analogy, the values in source-pvar are messages, the values in dest- 
address-pvar are the addresses of the mailboxes to which they are sent, and destina¬ 
tion-pvar is the set of mailboxes into which the messages are delivered. 

The arguments value-pvar and dest-address-pvar are only evaluated by the active 
processors of the current VP set. These arguments must be pvars belonging to the 
current VP set. 

The dest-pvar argument may be any pvar in any VP set; it does not need to belong to 
the current VP set. 

The dest-address-pvar may contain integer values that constitute valid send ad¬ 
dresses for the VP set to which dest-pvar belongs. Alternatively, an address object 
pvar may be used as the value of the dest-address-pvar argument. 

For all processors in the currently selected set, the value of value-pvar is sent to the 
processor addressed by dest-address-pvar, and stored into destination-pvar in the 
processor addressed by dest-address-pvar. 
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When dest-address-pvar contains duplicate addresses, some processors receive 
more than one value. When this occurs, the values received are combined accord¬ 
ing to the method specified by combine-method. The effect of each legal combine- 
method value is described below. 

: default An error is signaled if any processor receives more than 

one value. 

:no-collisions Asserts that no more than one value will be sent to each 
processor. If any processor does receive multiple values, 
the code is in error. 

-.overwrite One arbitrarily selected value is stored; all other values are 

ignored. 

:or The logical OR is stored. 

:and The logical AND is stored. 

: logior The bitwise OR is stored. The source-pvar must contain in¬ 

tegers only. 

:logand The bitwise AND is stored. The source-pvar must contain 

integers only. 

.-add The numerical sum is stored. 

:max The numerical maximum is stored. 

:min The numerical minimum is stored. 

The optional argument notify-pvar must be a pvar. When *pset has finished 
executing, the value of notify-pvar is t in each processor where destination-pvar has 
been altered, in other words, wherever a processor has received and stored a 
source-pvar value in destination-pvar — even if the value stored happens to be the 
same as the original value — notify-pvar is set The value of notify-pvar is left 
unchanged in processors where the destination-pvar has not been altered. 

If supplied, the vp-set argument must be the VP set to which destination-pvar be¬ 
longs. This argument is available solely for optimization and readability. If a vp-set 
argument is not supplied, *Lisp determines the proper VP set from destination- 
pvar. 

The collision-mode argument is superfluous as of Version 5.0, and is retained for 
compatibility purposes. 
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Examples- 

Here is a simple call to *pset: 

(*defvar pvar-a (random!! (!! 10))) 

(*defvar pvar-b) 

(*pset :no-collisions pvar-a pvar-b (self-address!!)) 

The value of pvar-a in each processor is stored in the corresponding processor of 
pvar-b. Because there is no possibility of more than one value being sent to the 
same processor, the: no-collisions option is used to increase efficiency. This exam¬ 
ple is identical in operation to a call to *set: 

(*set pvar-a pvar-b) 

In this example, data is copied from one pvar to another within each processor, so 
no interprocessor communication takes place. 

More interesting uses of *pset involve exchanging values between processors: 

(defun backwards (pvar) 

(*let (backwards-pvar) 

(*pset :default pvar backwards-pvar 

(-!! (!! (1- *number-of-processors-limit*)) 

(self-address!!))) 
backwards-pvar)) 

This function takes any pvar and returns a copy of that pvar with its values in re¬ 
verse send-address order. The *pset macro is used to transfer the value of pvar 
from each processor to the processor’s opposite in terms of send addresses, where 
the value is stored in backwards-pvar. So, for example, 

(*cold-boot :initial-dimensions '(10)) 

(ppp dest :end 10) 

displays the values 

9876543210 
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The next example is another function that calls * pset, this time to obtain the sum of 
the values of a pvar: 

(defun my-*sum (pvar) 

(declare (type (pvar (unsigned-byte 10)) pvar)) 

(pref (*let (the-sum-goes-here) 

(declare (type (pvar (unsigned-byte 32)) 
the-sum-goes-here)) 

(*all (*pset :add pvar the-sum-goes-here (!! 47))) 
the - sum-goes-here) 

47)) 

The function my-*sum uses *pset to sum a pvar over all the Connection Machine 
processors. Each processor sends its value to the same address, processor 47 (any 
legal send address can be substituted for 47). The values are collected using the 
:add method, which calculates and stores the sum. The pref operation is then used 
to read and return the sum. (Note: the *Lisp function *sum performs the same 
operation much more efficiently than this example.) 

An example of a realistic use for *pset is: 

(*defvar data-pvar (random!! (!! 10))) 

(defun histogram (pvar) 

(declare (type (pvar (unsigned-byte 4)) pvar)) 

(*let ((histogram (!! 0))) 

(declare (type (pvar (unsigned-byte 

*current-send-address-length*)) 

histogram)) 

(*pset :add (!! 1) histogram pvar) 
histogram)) 

This function creates and returns a histogram of the values in pvar. The call to 
* pset causes each processor to treat its value of pvar as a send address and send the 
value 1 to the processor at that address. The :add combine method is used, so each 
processor stores in histogram a count of the number of values in pvar which are the 
same as its send address. For example: 

(*defvar data-pvar (random!! (!! 10))) 

(ppp data-pvar :end 20) 

53941709141920903607 
(ppp (histogram data-pvar) :end 14) 

5273 6397 6808 7468 6952 8403 7691 4569 7774 4201 0000 
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This shows that, for example, there are 6808 occurrences of the value 2 in 

data-pvar. 

The *pset macro may also be used to transfer values between VP sets, as in the 
following example. 

(♦proclaim '(type (pvar (unsigned-byte 16)) 
one-d-pvar two-d-pvar)) 

(def-vp-set one-d "(128) 

:♦defvars 

((one-d-pvar (1+!! (self-address!!))))) 

(def-vp-set two-d "(128 128) 

:*defvars 

((two-d-pvar (!! 0)))) 

These forms define two VP sets, one-d and two-d, with one and two dimensions 
respectively. The VP set two-d is defined as a square grid with as many processors 
along its edge as there are processors in one-d. 

Two pvars are also defined, one associated with each VP set, having the following 
initial values: 

(ppp one-d-pvar :end 10) 

123456789 10 


(ppp two-d-pvar :mode :grid :end "(5 5)) 

DIMENSION 0 (X) -> 

0 0 0 0 0 
0 0 0 0 0 
0 0 0 0 0 
0 0 0 0 0 
0 0 0 0 0 
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The following expression uses the *pset macro to copy one-d-pvar into 
two-d-pvar in such a way that the values of one-d-pvar are stored on the diagonal 
of the grid of the two-d VP set. 

(*with-vp-set one-d ;;; VP set of source-pvar 
(*pset :no-collisions one-d-pvar two-d-pvar 
(cube-from-vp-grid-address!! two-d 

;;; Treat pair of send addresses from one-d 
;;; as grid address in two-d, and convert 
;;; to corresponding send address in two-d 
(self-address!!) 

(self-address!!)) 

:vp-set two-d)) ;;; VP set of dest-pvar 


(ppp two-d-pvar -.mode -.grid : end '(5 5)) 

DIMENSION 0 (X) -> 

1 0 0 0 0 
0 2 0 0 0 
0 0 3 0 0 
0 0 0 4 0 
0 0 0 0 5 

Note the use of cube-from-vp-grid-address!! to convert send addresses from 
one-d into send addresses for two-d along the diagonal of the grid. The send 
address of each value of one-d-pvar is used twice to form a grid address along the 
diagonal of two-d-pvar. This grid address is then converted by 
cube-from-vp-grid-address!! to the appropriate send address within the two-d 
VP set. 

Another way of converting grid addresses to send addresses within a *pset form is 
the use the grid!! function. For instance, the above call to *pset could have been 
written as 

(*pset :no-collisions one-d-pvar two-d-pvar 

(grid!! (self-address!!) (self-address!!)) 

:vp-set two-d) 

See the definition of grid!!, and Section 6.5, 'Address Objects” of the *Lisp 
Reference Supplement , Version 5.0, for more information. 
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Finally, the following function definition shows how the : notify argument to *pset 
can be used: 

(defun send-and-add (source dest address) 

"This function sums source into dest, and then counts" 

"How many processors actually summed up data." 

(*let (notify-pvar) 

(declare (type boolean-pvar notify-pvar)) 

(*all (*set notify-pvar nil!!)) 

(*pset :add source dest address :notify notify-pvar) 

(*all (*when notify-pvar 

(format t "~%~D processors summed data" 

(*sum (!! 1))))))) 

This function may be called with any number of processors selected. All 
processors are made active temporarily to initialize notify-pvar, and then a call is 
made to * pset to perform a send operation. The value of notify-pvar is then used to 
display the number of processors that actually transmitted data. First all 
processors are selected (since some processors receiving data may not be in the 
currently selected set), and then notify-pvar is used to select those processors that 
in fact received data. With these processors active, a call to *sum is made to return 
a count of those processors. 


Notes- 

The *pset macro invokes the general routing hardware of the Connection Ma¬ 
chine. While providing flexibility in communication of values between processors, 
the general router is less efficient than the communication methods employed by 
more specialized operators, such as "news, news!! and scan!!. 

Performance Considerations: 

The :or and :and combination methods are faster if the source-pvar contains 
only boolean values (t or nil). 

Cautions: 

The argument notify-pvar is unaltered in processors where destination-pvar is 
unaltered. The implications are: 

H This allows one to track the cumulative effects of multiple *pset calls. 
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H User code is responsible for the initial value of notify-pvar. In many cases it 
is advisable to set notify-pvar to nil!! in all processors prior to executing 

*pset. 

Errors: 

It is an error if any value copied is of a data type that cannot be stored in 
destination-pvar. 

It is an error if source-pvar and destination-pvar are structure pvars of a type 
defined to include a variable-length field, and if the length of that field is differ¬ 
ent in source-pvar and destination-pvar. For instance, if the length of the field is 
dependent on the value of *current-send-address-length* , and if source-pvar 
and destination-pvar belong to VP sets of different sizes, then *pset will fail. 

References- 

The function *pset copies data from one pvar to another, much as *set does. 
However, *pset is also able to exchange data between processors, whereas *set 
performs only a straight copy operation. See the *set Dictionary entry for de¬ 
tails. 

See also the related processor communication operator pref!!. 

See also these related NEWS communication operators: 

*news news!! news-border!! 

•news-direction news-direction!! 

See also these related off-grid processor address tests: 

off-grid-border-p!! off-grid-border-relative-direction-p!! 

off-grid-border-relative-p!! off-vp-grid-border-p!! 
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pvar-exponent-length [Function] 

Returns bit length of exponent of the supplied floating-point or complex pvars. 

Syntax- 

pvar-exponent-length pvar 

Arguments- 

pvar Floating-point or complex pvar. Pvar for which exponent bit 

length is determined. 

Returned Value- 

exponent-length Integer. Length in bits of exponent field of supplied pvar. 

Side Effects- 

None. 

Description- 

This function returns the bit-length of the exponent of pvar. 

The argument pvar may be any pvar, but only floating-point or complex pvars re¬ 
turn meaningful values. 
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Examples 


Notes 


References- 

See also the following general pvar information operators: 


allocated-pvar-p 

describe-pvar 


pvar-length 

pvar-location 

pvar-mantissa-length 

pvar-name 

pvarp 

pvar-plist 

pvar-type 

pvar-vp-set 
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pvar-length [Function] 

Returns bit length of the CM field associated with the supplied pvar. 

Syntax- 

pvar-length pvar 

Arguments- 

pvar Pvar expression. Pvar for which field bit length is determined. 

Returned Value- 

bit-length Integer. Length in bits of CM field associated with pvar. 

Side Effects- 

None. 

Description- 

This function returns the bit length of the field associated with pvar. This function 
can be used to supply field length arguments in calls to Paris routines. 

The argument pvar may be any pvar. 
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Examples 

Notes — 


References- 

See also the following general pvar information operators: 

allocated-pvar-p describe-pvar pvar-exponent-length 

pvar-location pvar-mantissa-length 

pvar-name pvarp pvar-plist 

pvar-type pvar-vp-set 
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pvar-location [Function] 

Returns field-id of the CM field associated with the supplied pvar. 

Syntax- 

pvar-location pvar 

Arguments- 

pvar Pvar expression. Pvar for which field-id is determined. 

Returned Value- 

field-id Integer. Field-id of CM field associated with pvar. 

Side Effects- 

None. 

Description- 

This function returns the field-id of the field associated with pvar. This function 
can be used to supply field-id arguments in calls to Paris routines. 

The argument pvar may be any pvar. 
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Examples 


Notes 


References 


See also the following general 

allocated-pvar-p 

pvar-length 

pvar-name 

pvar-type 


pvar information operators: 

describe-pvar pvar-exponent-length 

pvar-mantissa-length 

pvarp pvar-plist 

pvar-vp-set 
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pvar-mantissa-length [Function] 

Returns bit length of the mantissa of the supplied floating-point or complex pvars. 

Syntax- 

pvar-mantissa-length pvar 

Arguments- 

pvar Floating-point or complex pvar. Pvar for which mantissa bit 

length is determined. 

Returned Value- 

exponent-length Integer. Length in bits of mantissa field of supplied pvar. 

Side Effects- 

None. 

Description- 

This function returns the bit-length of the mantissa of pvar. 
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Examples 


Notes- 

References- 

See also the following general pvar information operators: 


allocated-pvar-p 

describe-pvar 

pvar-exponent-length 

pvar-length 

pvar-location 


pvar-name 

pvarp 

pvar-plist 

pvar-type 

pvar-vp-$et 
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pvar-name [Function] 

Returns the symbolic name of the supplied pvar. 

Syntax- 

pvar-name pvar 

Arguments- 

pvar Pvar expression. Pvar for which symbolic name is returned. 

Returned Value- 

name-symbol Symbol. Symbol recorded as the name of pvar. 

Side Effects- 

None. 

Description- 

This function returns the symbolic name of pvar. 

The argument pvar may be any pvar, but temporary pvars return nil. 


781 



pvar-name 


*Lisp Dictionary 


Examples 

Notes- 


References- 

See also the following general pvar information operators: 

allocated-pvar-p describe-pvar pvar-exponent-length 

pvar-length pvar-location pvar-mantissa-length 

pvarp pvar-plist 

pvar-type pvar-vp-set 
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pvarp [Function] 

Tests whether the supplied object is a pvar. 

Syntax- 

pvarp object 

Arguments- 

object Common Lisp or *Lisp data object to be tested. 

Returned Value- 

pvarp Boolean. The value t if object is a pvar, and nil otherwise. 

Side Effects- 

None. 

Description- 

This returns t if the argument is a pvar and nil if it is not. 
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Examples 

Notes — 


References- 

See also the following general pvar information operators: 

allocated-pvar-p describe-pvar pvar-exponent-length 

pvar-length pvar-location pvar-mantissa-length 

pvar-name pvar-plist pvar-type 

pvar-vp-set 
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pvar-plist [Function] 

Returns the property list of the supplied pvar. 

Syntax- 

pvar-plist pvar 

Arguments- 

pvar Pvar expression. Pvar for which property list is returned. 

Returned Value- 

property-list List. Property list of pvar. 

Side Effects- 

None. 

Description- 

This function returns the property list of pvar. 

The argument pvar may be any pvar. 
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Examples 


Notes 


References- 

See also the following general pvar information operators: 

allocated-pvar-p describe-pvar pvar-exponent-length 

pvar-length pvar-location pvar-mantissa-length 

pvar-name pvarp pvar-type 

pvar-vp-set 
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pvar-to-array [ * Defun] 

Copies values from a pvar to a front-end vector in send-address order. 


Syntax 


pvar-to-array source-pvar 


&optional dest-array 

&key :array-offset 

: cube-address-start 
:cube-address-end 


Arguments- 

source-pvar Pvar. Pvar from which values are copied. 

dest-array Front-end vector. Array into which values are stored. If this ar¬ 

gument is nil, the default, a front-end array of the appropriate 
size is created and returned. 

:array-offset Integer. Offset into dest-array at which first value is stored. 
Default is 0. 

: cube-address-start 

Send address. Processor at which copying will start. 

Default is 0. 


:cube-address-end 

Send address. Processor at which copying will end. 
Default is *number-of-processors-limit*. 


Returned Value- 

dest-array The destination array, into which values have been copied. 


Side Effects- 

The contents of source-pvar from :cube-address-start to :cube-address-end are 
copied into dest-array beginning at: array-offset. 
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Description- 

This function moves data from source-pvar into dest-array in send-address order. 

If provided, dest-array must be one-dimensional. If a dest-array is not provided, an 
array is created of size :cube-address-end minus :cube-address-start. 

The data from source-pvar in processors :cube-address-start through 
1 - :cube-address-end are written into the dest-array elements starting with ele¬ 
ment : array-offset. The result returned by pvar-to-array is dest-array. 


Examples- 

A sample pvar-to-array call is the expression 

(pvar-to-array (self-address!!) nil 
:cube-address-start 3 
:cube-address-end 10) 

which returns the array 

# (3 4 5 6 7 8 9) 

A call to pvar-to-array that uses the .-array-offset keyword is 

(pvar-to-array (self-address!!) nil 
.•array-offset 2 
:cube-address-start 3 
:cube-address-end 10) 

which returns the array 

#(NIL NIL 3456789) 
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Notes- 

Performance Note: 

The pvar-to-array function performs most efficiently when used on non-aggregate 
pvars of declared type and when the front-end array is of corresponding type to 
that of the pvar. 

For instance, transferring data from a pvar of type single-float into an array whose 
element type is single-float is very efficient. Transferring a general pvar into an 
array whose element type is t will not be as efficient. 

Transferring aggregate pvars (structures and arrays) using a single call to one of the 
functions array-to-pvar, pvar-to-array, pvar-to-array-grid, or array-to-pvar-grid 
is very slow. See the performance note under the definition of array-to-pvar for a 
discussion of how to transfer aggregate data efficiently between the front end and 
the CM. 

Syntax Note: 

Remember that when no dest-array argument is specified to the pvar-to-array and 
pvar-to-array-grid functions, anil must be provided instead if keyword arguments 
are to be used. 


References- 

See also these related array transfer operations: 

array-to-pvar array-to-pvar-grid 

pvar-to-array-grid 

See also the *Lisp operation pref, which is used to transfer single values from the CM 
to the front end. 

The *Lisp operation *setf, in combination with pref, is used to transfer a single value 
from the front end to the CM. 
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pvar-to-array-grid [* Defun] 

Copies values from a pvar to a front-end array in grid address order. 

Syntax- 

pvar-to-array-grid source-pvar &optional dest-array 
&key :array-offset 
: grid-start 
:grid-end 

Arguments- 

source-pvar Pvar. Pvar from which values are copied. 

dest-array Front-end array into which values are stored. Must have a rank 

equal to *number-of-dimensions*. If this argument is nil, the 
default, a front-end array of the appropriate size is created and 
returned. 

: array-offset Integer list. Set of offsets into source-array indicating location 
at which first value is stored. Default is (make-list ‘number- 
of-dimensions* :initial-element 0). 

:grid-start Integer list, specifying grid address of processor at which 

copying will start. Default is value of (make-list *number-of- 
dimensions* :initial-element 0). 

: grid-end Integer list, specifying grid address of processor at which copy¬ 

ing will end. Default is *current-cm-configuration*. 

Returned Value- 

dest-array The destination array, into which values have been copied. 

Side Effects- 

The contents of source-pvar from : grid-start to: grid-end are copied into dest-array 

beginning at: array-offset. 
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Description- 

This function moves data from source-pvar into dest-array in grid address order. 

If provided, dest-array must have the same number of dimensions as the current 
Connection Machine configuration. If dest-array is not specified, an array is cre¬ 
ated with dimensions :grid-end minus :grid-start, where the subtraction is done 
component-wise to produce a list suitable for make-array. The data from source- 
pvar in the sub-grid defined by :grid-start and :grid-end as the “upper-left” and 
“lower-right” corners, respectively, are written into a similar sub-grid of dest-array 
starting with element: array-offset as the upper-left corner. The arguments : array- 
offset, :grid-start, and :grid-end must be lists of length *number-of-dimensions*. 
The value returned by pvar-to-array-grid is dest-array. 


Examples- 

Assuming a two-dimensional grid has been defined, for which 
(ppp (self-address!!) -.mode :grid :end '(4 4)) 
displays the values 

0 4 8 12 

1 5 9 13 

2 6 10 14 

3 7 11 15 

then when the expression 

(pvar-to-array-grid (self-address!!) nil 
:grid-start '(1 1) :grid-end '(4 3)) 

is evaluated, it returns the array 

#2A((5 6) (9 10) (13 14)) 

and the expression 

(pvar-to-array-grid (self-address!!) nil 
:array-offset '(1 1) 

:grid-start '(1 1) :grid-end '(4 3)) 
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pvar-to-array-grid 


when evaluated, returns the array 

#2A((NIL NIL NIL) (NIL 5 6) (NIL 9 10) (NIL 13 14)) 

The following example shows the use of pvar-to-array-grid to extract a subgrid 
from a pvar and store it into a predefined front-end array: 

(*cold-boot :initial-dimensions '(128 128)) 

(defparameter an-array 

(make-array '(10 10) 

:element-type 'single-float 
:initial-element 0.0)) 

(♦proclaim '(type single-float-pvar data-pvar)) 

(♦defvar data-pvar (float!! (self-address!!))) 

(ppp data-pvar :mode :grid :end '(5 5) -.format "~5F ") 
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The following call to pvar-to-array-grid transfers the 4x4 subgrid of data-pvar 
whose corners are 

(1 1) (4 1) 

(1 4) (4 4) 

to the 4 x 4 subarray of an-array whose corners are 

(2 3) (6 3) 

(2 7) (6 7) 

(pvar-to-array-grid data-pvar an-array 

:array-offset '(2 3) 

:grid-start '(1 1) 

:grid-end '(5 5)) 

(aref an-array 2 3) => 9.0 
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Notes- 

Performance Note: 

The pvar-to-array-grid function performs most efficiently when used on non-ag¬ 
gregate pvars of declared type and when the front-end array is of corresponding 
type to that of the pvar. 

For instance, transferring data from a pvar of type single-float into an array whose 
element type is single-float is very efficient. Transferring a general pvar into an 
array whose element type is t will not be as efficient. 

Transferring aggregate pvars (structures and arrays) using a single call to one of the 
functions array-to-pvar, pvar-to-array, pvar-to-array-grid, or array-to-pvar-grid 
is very slow. See the performance note under the definition of array-to-pvar for a 
discussion of how to transfer aggregate data efficiently between the front end and 
the CM. 

Syntax Note: 

Remember that when no dest-array argument is specified to the pvar-to-array and 
pvar-to-array-grid functions, a nil must be provided instead if keyword arguments 
are to be used. 


References- 

See also these related array transfer operations: 

array-to-pvar array-to-pvar-grid 

pvar-to-array 

See also the *Lisp operation pref, which is used to transfer single values from the CM 
to the front end. 

The *Lisp operation *setf, in combination with pref, is used to transfer a single value 
from the front end to the CM. 
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pvar-type [Function] 

Returns the data type of the supplied pvar. 

Syntax- 

pvar-type pvar 


Arguments- 

pvar Pvar expression. Pvar for which data type is determined. 

Returned Value- 

data-type Symbol. Data type of pvar. 

Side Effects- 

None. 

Description- 

This function returns the data type of pvar. 

The argument pvar may be any pvar. 
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Examples 

Notes- 


References- 

See also the following general pvar information operators: 

allocated-pvar-p describe-pvar pvar-exponent-length 

pvar-length pvar-location pvar-mantissa-length 

pvar-name pvarp pvar-plist 

pvar-vp-set 
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pvar-vp-set [Function] 

Returns the VP set to which the supplied pvar belongs. 

Syntax- 

pvar-vp-set pvar 


Arguments- 

pvar Pvar expression. Pvar for which VP set is returned. 

Returned Value- 

vp-set *Lisp VP set object. VP set to which pvar belongs. 

Side Effects- 

None. 

Description- 

This function returns the VP set to which pvar belongs. 

The argument pvar may be any pvar. 
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Examples 

Notes — 


References- 

See also the following general pvar information operators: 

allocated-pvar-p describe-pvar pvar-exponent-length 

pvar-length pvar-locatiort pvar-mantissa-length 

pvar-name pvarp pvar-plist 

pvar-type 
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random!! [Function] 

Returns a pvar with a random value in each processor. 


Syntax- 

random !! limit-pvar 


Arguments- 

limit-pvar Non-complex numeric pvar. Upper exclusive bound on ran¬ 

dom number selected. Must contain positive values. 


Returned Value- 

random-pvar Temporary numeric pvar, of same type as limit-pvar. In each 
active processor, contains a random value between 0 inclusive 
and the value of limit-pvar exclusive. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of Common Lisp’s random function, and 
returns a pvar containing a random value in each processor. 
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Examples- 

For example, when the expression 

(ppp (random!! (!! 10)) :end 10) 

is evaluated, the first ten values of the random-valued pvar returned by random!! 
are displayed, for example 

8913402765 


Notes- 

This operation is faster when provided constant pvar arguments, as in the example 
above, than when applied to non-constant pvar arguments, as in 

(*set random-data (random!! data-pvar)) 


References 
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rank!! [ Function] 

Performs a parallel comparison, numerically ranking the values of the supplied 
numeric pvar. 

Syntax- 

rank!! numeric-pvar predicate &key :dimension :segment-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Pvar containing values to be com¬ 
pared. 

predicate Two-argument pvar predicate. Determines type of ranking. 

Currently limited by implementation to the function <=!!. 

dimension Integer or nil. Specifies dimension along which to perform 

ranking. The default, nil, specifies a send-address order rank¬ 
ing. If not nil, this argument must be an integer between 0 inclu¬ 
sive and *number-of-dimensions* exclusive. 

:segment-pvar Segment pvar or nil. Specifies segments in which to perform 
independent rankings. The default, nil, specifies an unseg¬ 
mented ranking. 

Returned Value- 

rank-pvar Temporary integer pvar. In each active processor, contains the 

numeric rank of the corresponding value of numeric-pvar 
among all of the active values of numeric-pvar, under the rela¬ 
tion specified by predicate. 

Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

The rank!! function returns a pvar containing values from 0 through one less than 
the number of active processors. The order of the values in the returned rank-pvar 
indicates the ranking of the values in the supplied numeric-pvar. 

The ranking is performed so that for any two active processors pi and p2, if the 
value of rank-pvar in pi is less than the value of rank-pvar in p2, then the value of 
numeric-pvar in processor pi satisfies the supplied predicate with respect to the 
value of numeric-pvar in processor p2. (The current implementation limits predi¬ 
cate to the operator <=!!.) 

The keywords, : dimension and :segment-pvar permit rankings to be taken along 
specific grid dimensions and within segments. 

The : dimension keyword specifies whether the ranking is done by send address 
order or along a specific dimension. If a dimension is specified, ranking is per¬ 
formed only along that dimension. The default value, nil, specifies a send-address 
order ranking. 

For example, assuming a two-dimensional grid, a: dimension argument of 0 causes 
ranking to occur independently in each “row” of processors along dimension 0. A 
: dimension argument of 1 causes ranking to occur independently in each “column” 
of processors along dimension 1 (see Figure 2). 
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Figure 2. Effect of different: dimension arguments, 
assuming a two-dimensional grid 
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The :segment-pvar argument specifies whether the ranking is performed sepa¬ 
rately within segments. The default is nil; rank! ! is by default unsegmented. If pro¬ 
vided, the :segment-pvar value must be a segment pvar. A segment pvar contains 
boolean values, with a non-nil value in the first processor of each segment and nil in 
all other processors. If a segment pvar is specified, then the ranking is done inde¬ 
pendently within each segment. 

If both a :dimension and a: segment pvar argument are specified, then the ranking 
is done independently for each “row” along the specified dimension and independ¬ 
ently within segments for each row. 


Examples- 

A simple call to rank!! is 

(rank!! numeric-pvar '<=!!) 

If the first 12 elements of numeric-pvar are 
0 20 4 16 8 12 10 14 6 18 2 22 
then the first 12 values of the returned rank-pvar are 
0 10 284657391 11 

An example of rank!! with a :segment-pvar argument is 

(rank!! numeric-pvar '<-\! 

:segment-pvar (evenp!! (self-address!!))) 

If the first 12 elements of numeric-pvar are 
024217534782 
then the first 12 values of the returned rank-pvar are 
011001100110 


803 




rank!! 


*Lisp Dictionary 


An example of rank!! with a idimension argument is 

(rank!! (self-address!!) ! idimension 1) 

Assuming a two-dimensional VP set geometry, if the expression 

(*defvar random-values (random!! (!! 32))) 

(PPP random-values imode igrid :end '(4 4)) 

displays the values 

0 7 8 15 

1 6 10 13 

2 5 9 14 

3 4 11 12 

then the expression 

(ppp (rank!! random-values '<=!! idimension 1) 
imode igrid lend '(4 4)) 

will display the values 

0 3 0 3 

12 2 1 
2 112 
3 0 3 0 

The function sort! ! might be implemented using a combination of rank! ! and * pset, 
as follows: 

(*cold-boot iinitial-dimensions '(8)) 

(*defvar random-values (random!! (!! 32))) 

(ppp random-values) 

22 17 5 31 0 4 12 4 

(defun my-sort!! (unsorted-pvar) 

(*let (sorted-pvar) 

(*pset ino-collisions unsorted-pvar sorted-pvar 

(rank!! sorted-pvar) 

sorted-pvar))) 
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Notes- 

The ranking performed by rank!! is not guaranteed to be stable. If numeric-pvar 
contains the same value in two or more active processors, the ordering returned for 
these values in rank-pvar is arbitrary and indeterminate. 


References- 

See also the related functions 

enumerate!! self!! 

self-address!! self-address-grid!! sort!! 
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real part!! [Function] 

Extracts the real component from a complex pvar. 


Syntax- 

realpart!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar from which real part is extracted. 

Returned Value- 

realpart-pvar Temporary numeric pvar. In each active processor, contains 
the real part of the corresponding value of numeric-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a temporary pvar containing in each processor the real com¬ 
ponent of the complex value in numeric-pvar. Note that numeric-pvar need not be 
explicitly a complex-valued pvar. Non-complex values are automatically coerced 
into complex values with a zero imaginary component. 
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Examples 


Notes 


References- 

See also these related complex pvar operators: 

abs!! cis!! complex!! 

conjugate!! imagpart!! phase!! 
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reduce!! [ Function] 

Combines elements of a sequence pvar in parallel using a binary pvar function. 


Syntax- 

reduce!! function sequence-pvar &key :from-end :start :end :initial-value 


Arguments 


function Two-argument pvar function. Used to combine elements of se- 

quence-pvar in parallel. 

sequence-pvar Sequence pvar. Pvar containing sequences to be reduced. 


:from-end 


Scalar boolean. Whether to begin search from end of sequence. 
Defaults to nil. 


: start Integer pvar. Index, zero-based, of sequence element at which 

reduction operation starts. If not specified, search begins with 
first element. 


:end Integer pvar. Index, zero-based, of sequence element at which 

reduction operation ends. If not specified, search continues to 
end of sequence. 

: initial-value Pvar, of same type as elements of sequence-pvar. If supplied, is 

included in reduction operation as first value supplied to func¬ 
tion. 


Returned Value- 

reduce-pvar Temporary pvar, of same type as elements of sequence-pvar. In 

each active processor, contains result of reducing the corre¬ 
sponding sequence of sequence-pvar by the supplied function. 

Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

The function reduce! ! is similar to the Common Lisp function reduce. It operates 
in each processor to combine all the elements oi sequence-pvar, two at a time, using 
function. A pvar containing the reduction result in each processor is returned. 

The argument function must be a binary operation that accepts pvar arguments of 
the type contained in sequence-pvar. The argument sequence-pvar must be a vector 
pvar. 

The keyword :f rom-end takes a boolean and defaults to nil. Reduction is left-asso¬ 
ciative in any processor with a :from-end value of nil. Otherwise, reduction is 
right-associative. 

The keywords : start and :end define a subsequence of sequence-pvar. 

The keyword :initial-value takes a pvar of the same type as the elements of se- 
quence-pvar and provides an initial value for the reduction calculation. If an 
: initial-value value is supplied, it is logically placed at the beginning of 
sequence-pvar and included in the reduction. If :from-end is t, the value of 
: initial-value is logically placed at the end of sequence-pvar. 


Examples- 

The expression 

(reduce!! #'+!! number-sequence-pvar) 

adds up the elements of number-sequence-pvar in each processor. 


Notes- 

Language Note: 

Although the function reduce! ! is in many way similar to the Common Lisp func¬ 
tion reduce, it is not exactly identical, for while reduce can return any Common 
Lisp value, reduce!! can only return a pvar of the same type as the elements of 
sequence-pvar. 
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Compiler Note: 

Because of the utility of the reduce!! function for vector pvar operations, the 
*Lisp compiler will compile this function, but only under certain conditions. 
Specifically, for reduce!! to compile, the function argument must be a 
compilable function, and none of the keyword arguments may be used. 


References- 

See also these related *Lisp sequence operators: 

copy-seq!! ‘fill length!! 

‘nreverse reverse!! subseq!! 

See also the generalized array mapping functions amap!! and ‘map. 
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reduce-and-spread!! [Function] 

Performs a scan!! reduction along the specified dimension of the currently defined 
grid, and then a backwards copy! ! scan to spread the result values to all processors 
along the scanned dimension. 

Syntax- 

reduce-and-spread!! pvar function dimension 

Arguments- 

pvar Pvar expression. Pvar containing values to be reduced. 

function Two-argument pvar function. Determines type of reduction. 

May be any of+!!, and!!, or!!, logand!!, logior!!, logxor!!, max!!, 
min!!, and copy!!. 

dimension Integer. Index, zero-based, of dimension of currently defined 

grid along which reduction is performed, and the result values 
are copied. 

Returned Value- 

scan-pvar Temporary pvar. A copy of pvar to which the reduction opera¬ 

tion specified by function has been applied, with the result 
spread to every processor along the dimension specified by 
dimension. 


Side Effects- 

The returned pvar is allocated on the stack. 


813 




reduce-and-spread!! 


*Lisp Dictionary 


Description-— 

Conceptually, this function first performs a 

(scan!! pvar function .'dimension dimension) 

It then takes the scan!! result from the last active processor along the scanning 
dimension and performs a backwards copy!! scan. A pvar containing the result of 
this copy scan is returned. Thus, the scan!! results are spread to all the processors 
which participated in the reduce-and-spread!!. 

The dimension argument determines the grid dimension along which the operation 
is performed. It must be either a non-negative integer scalar within the range of 
dimensions of the VP set to which pvar belongs, or nil. If dimension is nil, 
send-address order scanning is done. 

For example, assuming a two-dimensional grid, a dimension argument of 0 causes 
ranking to occur independently in each “row” of processors along dimension 0. A 
dimension argument of 1 causes ranking to occur independently in each “column” 
of processors along dimension 1 (see Figure 3). Because the grid has only two 
dimensions, the only valid arguments for dimension are 0, 1, and nil. 
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Figure 3. Effect of different dimension arguments, 
assuming a two-dimensional grid 
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Examples- 

This example shows how reduce-and-spread may be used, assuming a two-dimen¬ 
sional grid configuration for simplicity. Note that the reduction and spread opera¬ 
tion is performed along dimension 1, that is, down the “columns” of the grid. 

(*cold-boot -.initial-dimensions ' (4 4)) 

(ppp (self-address!!) :mode :grid :format M ~2D ") 

0 4 8 12 

1 5 9 13 

2 6 10 14 

3 7 11 15 

(ppp (reduce-and-spread!! (self-address!!) '+!! 1) 

:mode :grid :format ""2D ") 

6 22 38 54 
6 22 38 54 
6 22 38 54 
6 22 38 54 


Notes 


Performance Note: 

This function is provided because it may be significantly faster to use it than to do a 
scan!! followed by a reverse copy scan. 


References- 

See also these related operations: 

scan!! segment-set-scan!! spread!! 
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rem!! [Function] 

Calculates in parallel the remainder of a division on the supplied pvars. 


Syntax- 

rem!! numeric-pvar divisor-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Pvar for which remainder is cal¬ 
culated. 

divisor-pvar Integer pvar. Pvar by which numeric-pvar is divided. 


Returned Value- 

remainder-pvar Temporary numeric pvar, of same type as numeric-pvar. In 
each active processor, contains the remainder from dividing 
the value of numeric-pvar by the value of divisor-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp function rem. It is an 
error if divisor-pvar contains zero in any processor. 


817 



r e m!! *Lisp Dictionary 

Examples- 

Notes- 

References- 
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reverse!! [Function] 

Returns a copy of the supplied sequence pvar in which each sequence has been re¬ 
versed. 

Syntax- 

reverse!! sequence-pvar 

Arguments- 

sequence-pvar Sequence pvar. Pvar containing sequences to be reversed. 

Returned Value- 

reverse-pvar Temporary sequence pvar. In each active processor, contains a 
reversed copy of the corresponding sequence of sequence-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a sequence pvar that is a reversed copy of sequence-pvar. The 
argument sequence-pvar must be a vector pvar. The following equivalence always 
holds: 

(reverse!! sequence-pvar) 

<=> 

(*nreverse (copy-seq!! sequence-pvar)) 
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Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See also these related *Lisp sequence operators: 

copy-seq!! *f ill length!! 

•nreverse reduce!! subseq!! 

See also the generalized array mapping functions amap!! and "map. 
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♦room [Function] 

Prints and returns information about CM memory use. 

Syntax- 

*room &key :how :print-statistics : stream 

Arguments- 

:how One of :by-vp-set, :by-pvar, or :totals. Specifies how usage in¬ 

formation is to be displayed. Default is : by-vp-set. 

: print-statistics Scalar boolean. Whether to print results as well as returning 

values. Defaults to t. 

•.stream Stream object or t. Stream to which results are printed. De¬ 

faults to t, sending output to * standard-output* stream. 

Returned Values- 

stack-bytes Integer. Number of bytes of CM memory in use by temporary 

pvars on the *Lisp stack. 

temp-bytes Integer. Number of bytes of CM memory in use by permanent 

pvars on the *Lisp heap that were created by allocate!!. 

defvar-bytes Integer. Number of bytes of CM memory in use by permanent 
pvars on the *Lisp heap that were created by *defvar. 

overhead-bytes Integer. Number of bytes of CM memory in use as overhead. 

Side Effects- 

None. 


821 



room 


*Lisp Dictionary 


Description- 

Collects and prints information about CM memory usage. 

The ‘room function returns four values. Each return value indicates the total 
amount of CM memory in use for a particular purpose at the time of the call. 

■ The first return value reports the total number of bytes of CM memory al¬ 
located on the *Lisp stack. 

■ The second return value reports the total number of bytes of CM memory 
on the heap allocated to pvars created with allocate!!. 

■ The third return value reports the total number of bytes of CM memory on 
the heap allocated to pvars created with ‘defvar. 

■ The fourth return value reports the total number of bytes of CM memory in 
use as overhead, including overhead for the *Lisp VP mechanism and over¬ 
head for Paris. 

The :how keyword argument must be either :by-vp-set (the default), :by-pvar, or 
:totals. If the value of :how is : by-vp-set, then the four statistics are collected and 
printed for each existing *Lisp VP set. If the value of :how is :by-pvar, then 
statistics are given for each pvar as well as for each VP set. If the value of :how is 
:totals, then only summary information is printed. The :how keyword argument 
specifies only how memory information is printed; it has no impact on the values 
returned by ‘room. 

The: print-statistics keyword defaults to t. If it is set to nil, the results are returned 
but not printed and the :how keyword is ignored. 

The: stream keyword defaults to t, indicating that output goes to the standard out¬ 
put device. An alternate stream may be specified. 


Examples 


Notes 


References 


822 




*Lisp Dictionary 


rot!! 


rot!! [Function] 

Performs a parallel bit rotation on the supplied integer pvar. 


Syntax- 

rot!! integer-pvar n-pvar word-size 


Arguments — 

integer-pvar 

n-pvar 


word-size 


Integer pvar. Pvar containing values to be rotated. 

Integer pvar. Number of bits to rotate integer-pvar. Positive 
value rotates towards high-order bits, negative towards low- 
order bits. 

Integer pvar. Number of low-order bits of integer-pvar that are 
rotated. 


Returned Value- 

rot-pvar Temporary integer pvar. In each active processor, contains a 

copy of the low-order word-size bits of integer-pvar rotated the 
number of bits specified by the value of n-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns integer-pvar rotated left n-pvar bits, or rotated right if n-pvar 
is negative. The rotation considers each value of integer-pvar to be an integer of 
length word-size bits. 
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Examples 

Notes- 

This function is especially fast when n-pvar and word-size are both constant pvars. 

References- 
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round!! [Function] 

Performs a parallel round operation on the supplied pvar(s). 


Syntax- 

round!! numeric-pvar &optional divisor-numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Value to be rounded. 
divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di 
vided by divisor-numeric-pvar before rounding. 


Returned Value- 

round-pvar Temporary integer pvar. In each active processor, contains the 

rounded value of numeric-pvar, divided by divisor-numeric- 
pvar if supplied. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function round, except that only 
one value (the rounded quotient) is computed and returned. The round!! function 
rounds numbers to the nearest integer. If a number is exactly halfway between two 
integers, it is rounded towards the even integer. 
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\ 


Examples 


Notes 


References- 

See also these related rounding operations: 
ceiling!! floor!! truncate!! 

See also these related floating-point rounding operations: 

fceiling!! ffloor!! f round!! ftruncate!! 
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row-major-aref!! [Function] 

References the supplied multidimensional array pvar as a vector pvar with elements in 
row-major order. 


Syntax- 

row-major-aref!! array-pvar row-major-index-pvar 


Arguments- 

array-pvar Array pvar. Pvar to be referenced. 

row-major-index-pvar 

Integer pvar. Index of element in array-pvar to retrieve. 


Returned Value- 

row-major-aref-pvar 

Temporary pvar, of same type as elements of array-pvar. In 
each active processor, contains the element of array-pvar at the 
location referenced by row-major-index-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

References the specified array pvar as if it were a vector pvar, with elements taken 
in row-major order. The result is returned as a pvar. 

The array-pvar argument may be any array pvar. If this is a vector pvar (a one¬ 
dimensional array pvar), then this function is equivalent to aref!!. 

The row-major-index-pvar must contain integers in the range [0...JV], where N is 
one less than the total number of elements in array-pvar. In each processor, this 
value specifies the row-major index of a single element in the component array. 
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row-major-aref!! 

Examples- 

Consider the following: 

(*defvar ray-array (!! #2A((5 8) (3 0)))) 

(pref (row-major-aref!! my-array (!! 2)) 19) => 3 

In each processor is stored the array: 5 8 

3 0 

The element with row-major index 2 is referenced using row-major-aref!!. This 
results in a pvar whose value is 3 everywhere. The pref function then references this 
value in the 19th processor, yielding 3. 

It is legal to compose *setf with row-major-aref!!. For example, 

(*setf (row-major-aref!! my-array (!! 2)) (!! 25)) 

stores the value 25 in the third element of the component array in each processor, 
(pref (row-major-aref!! my-array (!! 2)) 19) => 25 


Notes- 

Usage Note: 

The row-major-aref!! function can be used to implement subroutines that per¬ 
form operations on arrays of any dimensionality. 


References- 

See also the related array-referencing operations: 

aref!! row-major-sideways-aref!! sideways-aref!! 

The following operations convert arrays to and from sideways orientation: 
"processorwise *sideways-array *slicewise 

See also the *map and amap!! functions for another way to iterate in row-major 
order over the elements of array pvars of any dimensionality. 
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row-major-sideways-aref!! 


row-major-sideways-aref!! [Function] 

References the supplied multidimensional sideways (slicewise) array pvar as a vector 
pvar with elements in row-major order. 

Syntax- 

row-major-sideways-arefl! array-pvar row-major-index-pvar 

Arguments- 

array-pvar Sideways array pvar. Pvar to be referenced. 

row-major-index-pvar 

Integer pvar. Index of element in array-pvar to retrieve. 


Returned Value- 

row-major-aref-pvar 

Temporary pvar, of same type as elements of array-pvar. In 
each active processor, contains the element of array-pvar at the 
location referenced by row-major-index-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

References the specified sideways (slicewise) array pvar as if it were a vector pvar, 
with indices taken in row-major order. The result is returned as a pvar. 

The row-major-index-pvar must contain integers in the range [O.JV], where N is 
one less than the number of elements in array-pvar. In each processor, this value 
specifies the row-major index of a single element in the component array. 
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Examples- 

Consider the following: 

(♦proclaim '(type (array-pvar (unsigned-byte 8) '{2 2)) 
my-sideways-array)) 

(*defvar my-sideways-array (!! #2A((5 8) (30)))) 

In each processor is stored the array: 5 8 

3 0 

The array is turned sideways, and is verified to be sideways. 

(♦slicewise my-sideways-array) 

(sideways-array-p my-sideways-array) => T 

In the following example, a different index into my-sideways-array is calculated in 
each processor, and then the array elements corresponding to those indices are 
accessed using row-major-sideways-aref!!. 

(ppp (row-major-sideways-aref!! my-sideways-array 
(mod!! (self-address!!) (!! 4))) 

:end 14) 

58305830583058 

It is legal to compose *setf with row-major-sideways-aref!!. For example, 

(*setf (row-major-sideways-aref!! my-sideways-array 
(!! 2 )) 

(!! 25)) 

stores the value 25 in the third element of the component array in each processor. 

(ppp (row-major-sideways-aref!! my-sideways-array 
(mod!! (self-address!!) (!! 4))) 

:end 14) 

58 25 058 25 058 25 058 
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row-major-sldeways-aref!! 


Notes 


References- 

See also the related array-referencing operations: 

aref!! row-major-aref!! 

sideways-aref!! 

The following operations convert arrays to and from sideways orientation: 

*processorwise * sideways-array *slicewise 
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Sbit!! [Function] 

Selects in parallel a bit at a given location in a simple bit array pvar. 

Syntax- 

sbit!! bit-array-pvar &rest pvar-indices 

Arguments- 

bit-array-pvar 
pvar-indices 

Returned Value 

bit-pvar Temporary bit pvar. In each processor, contains the bit re¬ 

trieved from the corresponding array of bit-array-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a temporary pvar whose value in each processor is the ele¬ 
ment of the bit-array in bit-array-pvar referenced by pvar-indices. This function is 
similar to bit!!, but bit-array-pvar is expected to be a simple array, i.e., a non-dis- 
placed, static array that has no fill pointer. 


Simple bit array pvar. Array from which bit is selected. 

Integers. Must be valid subscripts for bit-array-pvar. Specifies 
location of bit to return. 
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Examples 


Notes 


References 
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scale-float!! 


scale-float!! [Function] 

Multiplies the supplied floating-point pvar by the specified power of two. 


Syntax- 

scale-float!! float-pvar power-of-two-pvar 


Arguments- 

float-pvar Floating-point pvar. Pvar to be scaled. 

power-of-two-pvar Integer pvar. Power of two by which float-pvar is scaled. 


Returned Value- 

scale-float-pvar Temporary floating-point pvar. In each active processor, con¬ 
tains the corresponding value of float-pvar multiplied by two to 
the power specified by power-of-two-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function takes a floating-point pvar and an integer pvar; it returns, in each 
processor, that processor’s float-pvar component multiplied by two to that proces¬ 
sor’s power-of-two-pvar component power. 
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Examples- 

(scale-float!! (!! 3.5) (!! -1)) <=> (!! 1.75) 
(scale-float!! (!! 1.0) (!! 2)) <=> (!! 4.0) 

Notes- 

References- 
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scan!! [Function] 

Performs a cumulative reduction operation on the supplied pvar, either by send 
address or along a specified dimension of the currently defined grid. 

Syntax- 

scan!! pvar function &key :direction :segment-pvar 

:include-self :dimension identity 

Arguments- 

pvar Pvar expression. Pvar containing values to be scanned. 

function Two-argument pvar function. Determines type of scan. May be 

any of +!!, *!!, and!!, or!!, logand!!, logior!!, logxor!!, max!!, 
min!!, and copy!!, or a user-defined function, in which case a 
value must be supplied for the identity argument. 

direction Either : forward or : backward. Determines direction of scan 

through send addresses or across grid. Default is forward. 

:segment-pvar Boolean pvar containing the value t in each processor that 
starts a segment, and the value nil elsewhere. Determines seg¬ 
ments within which scanning takes place. If not supplied, an 
unsegmented scan is performed. 

:include-self Boolean. Determines whether to include the value contained in 
each processor in the scan calculation for that processor. 
Default is t. 

:dimension Integer. Index, zero-based, of dimension of currently defined 

grid along which scanning is performed. If not supplied, a 
send-address order scan is performed. 

identity Pvar expression. Identity element for function. Must be 

supplied if function is not a specialized scanning function. 
Ignored otherwise. 
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Returned Value- 

scan-pvar Temporary pvar. A copy of pvar to which the scanning opera¬ 

tion specified by function has been applied. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The scan!! function performs a cumulative reduction operation on the supplied 
pvar, either by send address or along one dimension of the currently defined grid. 

“Reducing” in this context refers to the Common Lisp function reduce, which ac¬ 
cepts two arguments, function and sequence. The reduce function applies function, 
which must be a binary associative function, to all the elements of the sequence. 
For example, if + were the function all the elements in sequence would be summed. 
In the case of a scan! ! function, the sequence becomes the pvar values contained in 
the ordered set of selected processors. 

For each selected processor, the value returned to that processor is the result of 
reducing the pvar values in all the processors preceding it. Its own pvar value is 
also, by default, included in the reduction. 

The function argument may be one of the associative binary pvar functions +!!, 
and!!, or!!, logand!!, logior!!, logxor!!, max!!, min!!, or copy!!, in which case an 
efficient “specialized scan” is performed. In addition, other associative binary 
pvar operators may be supplied, including user-defined pvar functions, in which 
case a less efficient “generalized scan” is performed. 

The function *!! is a special case; if used to perform a scan on a floating-point pvar, 
it performs as efficiently as one of the specialized scan operators listed above. If 
applied to any other numeric arguments, it is treated as a generalized scan 
operator. 

The direction keyword controls the direction of the scan through send addresses 
or across the grid. The default value for this argument, the keyword -.forward, 
causes the scan to be performed in order of ascending send or grid addresses. The 
keyword :backword causes the scan to be performed in descending order. 
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The :$egment-pvar argument provides a limited segmented scan functionality, 
which permits independent scans to be perfomed within mutually exclusive groups 
of processors, known as “segments.” It must be a boolean pvar containing the value 
t in each processor that starts a segment, and nil elsewhere. The end of each 
segment is determined by the starting point of the next segment. More advanced 
segmented scans, in particular scans with non-contiguous segments, are possible 
through the function segmented-set-scan!!. 

The boolean keyword argument :include-self controls whether the scan result 
calculated in each processor includes the value of pvar in that processor. When 
:include-self is nil, the result of the scan!! operation is undefined in the first active 
processor of the first segment. Also, when :inciude-self is nil, the result of the 
scan!! operation in the first processor of each of the other segments is the 
cumulative result of the scan!! operation over all active processors in the 
immediately preceding segment. 

The :dimension keyword value defaults to nil, indicating that the scan is performed 
in send address order. Alternatively, dimension may be given as an integer between 
0 and one less than the rank of the current VP set. If dimension is an integer value, 
the scan operation is performed along that dimension. If desired, dimension may 
be specified as :x, :y, or :z; these are equivalent to dimensions 0,1, and 2. For exam¬ 
ple, the expression 

(scan!! pvar 'copy!! :dimension :z) 

copies the value of each point in thex,y plane atz=0 into the corresponding point 
in the jc, y plane at z = 1, and thence to x, y at z = 2, and so on to z=n, where n is the 
extent of z. 

If a generalized scan is performed, an identity keyword value must be supplied. If 
supplied, the value of : identity must be the parallel identity element for function. 
That is, if function is applied to the identity pvar in combination with any legal pvar 
value P, then the result is P. It is an error to specify the : identity keyword for spe¬ 
cialized scans. 


Examples- 

If function is the function +!!, scan! ! performs a summation over the set of selected 
processors, ordered by cube address as shown below: 

(self-address!!) =>01234567... 

(scan!! (self-address!!) '+!!)) => 0 1 3 6 10 15 21 28 ... 
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In the next example there are four segments. The first is 0,1,2; second is 3; third is 
4, 5, 6; and fourth is 7.... 

(self-address!!) => 01234567... 

segment-pvar => t nil nil t t nil nil t . . . 

(scan!! (self-address!!) ' + !! 

:segment-pvar segment-pvar) => 0 1 3 3 4 9 15 7... 

The direction of the scanning is normally from lowest to highest cube-address. If 
the -.direction argument is : backward, then the scan is from highest to lowest cube- 
address. When scanning backward, segments are sequences of processors in de¬ 
scending cube-address order. For example, below we see three segments: the first is 
7, 6, 5; the next is 4; and the last is 3, 2, 1, 0. 


(self-address!!) 

=> 

0 

1 

2 

3 

4 

5 

6 

7 

segment-pvar 

(scan!! (self-address!!) '+\! 

=> 

nil 

nil 

nil 

t 

t 

nil 

nil 

t 

:segment -pvar segment -pvar 
:direction :backward) 

=> 

6 

6 

5 

3 

4 

18 

13 

7 

Following are two further examples using +!! with segmented scans. (The 

indicates a pvar value that is not defined.) 










(self-address!!) 

=> 

0 

1 

2 

3 

4 

5 

6 

7 

segment-pvar 

(scan!! (self-address!!) ' + !! 

=> 

t 

nil 

nil 

t 

t 

nil 

nil 

t 

:segment-pvar segment-pvar 
:include-self t) 

=> 

0 

1 

3 

3 

4 

9 

15 

7 

(scan!! (self-address!!) '+!! 










:segment -pvar segment -pvar 
:include-self nil) 

=> 

* 

0 

1 

3 

3 

4 

9 

15 


The use of the keyword argument :include-self with a value of nil prevents each 
processor from including its own value for (self-address!!) in the scan. Note that 
the result of the scan is not defined for processor 0 in the second scan example, and 
that result of the scan in the first processor of each of the other segments is the 
cumulative sum of the values in the immediately preceding segment. 
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The next example, using the max!! function, illustrates the double effect achieved 
when : include-self is nil. (Again, the “*” indicates a pvar value that is not defined.) 


pvar 

segment-pvar 
(scan!! pvar 'max!! 

:segment -pvar segment -pvar 
:include-self t) 

(scan!! pvar 'max!! 

:segment -pvar segment -pvar 
:include-self nil) 


=> 1 10 5 20 3 4 5 6 . . . 

=> t nil nil t t nil nil t . . . 

» 1 10 10 20 3 4 5 6 . . . 

=> * 1 10 10 20 3 4 5 .. . 


The next example demonstrates the used of copy! ! with segmented scans: 


(self-address!!) 

=> 

0 

12 3 

4 5 6 7 

segment-pvar 

(scan!! (self-address!!) 'copy! 

=> 

1 

t 

nil nil t 

t nil nil t 

:segment-pvar segment-pvar 
:include-self t) 

=> 

0 

0 0 3 

4 4 4 7 


The scan! ! function can also be used to perform scans on multi-dimensional grids. 
For example, assuming a two-dimensional grid is defined for which the expression 

(ppp (self-address!!) :mode :grid :end '(4 4)) 

displays the values 

0 4 8 12 

1 5 9 13 

2 6 10 14 

3 7 11 15 

then the expression 

(ppp (scan!! (self-address!!) '+!! dimension 0) 

:mode :grid :end '(4 4)) 

displays the values 

0 4 12 24 

1 6 15 28 

2 8 18 32 

3 10 21 36 
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and the expression 

(PPP (scan!! (self-address!!) '+!! :dimension 1) 

:mode :grid :end '(4 4)) 

displays the values 

0 4 8 12 

1 9 17 25 

3 15 27 39 
6 22 38 54 

The following example shows a segmented backwards copy!! scan along dimension 
1 of the grid with an :include-$elf value of nil. If the expression 

(PPP (self-address!!) :mode :grid :end '(4 5)) 

displays the values 

0 5 10 15 

1 6 11 16 

2 7 12 17 

3 8 13 18 

4 9 14 19 

then 

(ppp (scan!! (self-address!!) 'copy!! 

:dimension 1 
:direction :backwards 

:segment-pvar (evenp!! (self-address-grid!! (!! 1))) 

:include-self nil) 

:mode :grid 
:end '(4 4)) 

displays the values 

2 7 12 17 

2 7 12 17 

4 9 14 19 

4 9 14 19 
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Finally, an example of a “generalized” scan is the following expression. A function 
that performs 2x2 parallel matrix multiplication is supplied as the value of 
function , and specifies the identity matrix as the : identity argument. 

(scan!! my-parallel-matrix "my-matmult2x2!! 

•.identity (!! (make-array "(2 2) 

:initial-contents "((10) (01))))) 


Notes- 

Performance Notes: 

Providing a generalized function to scan!! results in significantly slower 
performance than providing one of the standard, specialized functions. 

Scans are performed essentially in constant time. However, at high VP ratios 
scan performance is improved because of the high number of sends performed 
between virtual processors located on the same physical chip. 

Compiler Note: 

Generalized scans do not compile. 


References- 

See also these related operations: 

create-segment-set!! reduce-and-spread!! 

segment-set-scan!! spread!! 
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segment-set-end-address 


segment-set-end-address [Function] 

Returns the contents of the end-address slot of a segment set structure object. 

Syntax- 

segment-set-end-address segment-set-object 

Arguments- 

segment-set-object 

Segment set structure object created by create-segment-set!!. 

Returned Value- 

end-address Integer. Send address of last processor in segment to which 

segment-set-object belongs. 


Side Effects 

None. 


Description- 

This is the front-end version of the segment-set-end-address! ! accessor function. 
It takes a segment set object, as returned by create-segment-set! !, and returns the 
contents of the end-address structure slot. 
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Examples 


Notes 


References- 

For information about the components of a segment set structure object, see the 
dictionary entry for create-segment-set!!. 

See also these related segment set operators: 

segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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segment-set-end-address!! 


segment-set-end-address!! [Function] 

Extracts in parallel the contents of the end-address slot of the supplied segment set 
pvar. 


Syntax- 

segment-set-end-address! ! segment-set-pvar 


Arguments- 

segment-set-pvar Segment set pvar, as returned by create-segment-set!!. 


Returned Value- 

end-address-pvar Temporary integer pvar. In each active processor, contains the 
contents of the end-address slot of the corresponding value of 
segment-set-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This accessor function returns the contents of the end-address slot of a segment 
set pvar, as returned by a call to create-segment-set!!. 
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Examples 


Notes 


References- 

For information about the components of a segment set structure pvar, see the dic¬ 
tionary entry for create-segment-set!!. 

See also these related segment set operators: 
segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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segment-set-end-bits [Function] 

Returns the contents of the end-bits slot of a segment set structure object. 

Syntax- 

segment-set-end-bits segment-set-object 

Arguments- 

segment-set-object 

Segment set structure object created by create-segment-set!!. 

Returned Value- 

end-bits Boolean. The value t if this segment set object is the last in its 

segment, and the value nil if not. 

Side Effects- 

None. 


Description- 

This is the front-end version of the segment-set-end-bits!! accessor function. It 
takes a segment set object, as returned by create-segment-set!!, and returns the 
contents of the end-bits structure slot. 
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segment-set-end-bits 


Examples 


Notes 


References- 

For information about the components of a segment set structure object, see the 
dictionary entry for create-segment-set!!. 

See also these related segment set operators: 

segment-set-scan!! 
segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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segment-set-end-bits!! [Function] 

Extracts in parallel the contents of the end-bits slot of the supplied segment set pvar. 

Syntax- 

segment-set-end-bits !! segment-set-pvar 

Arguments- 

segment-set-pvar Segment set pvar, as returned by create-segment-set!!. 

Returned Value- 

end-bits-pvar Temporary integer pvar. In each active processor, contains the 
contents of the end-bits slot of the corresponding value of seg¬ 
ment-set-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This accessor function returns the contents of the end-bits slot of a segment set 
pvar, as returned by a call to create-segment-set!!. 


851 




segment-set-end-bits!! 


*Lisp Dictionary 


Examples 


Notes 


References- 

For information about the components of a segment set structure pvar, see the dic¬ 
tionary entry for create-segment-set!!. 

See also these related segment set operators: 

segment-set-scan!! 
segment-set-end-bits 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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segment-set- [Function] 

processor-not-in-any-segment 

Returns the contents of the processor-not-in-any-segment slot of a segment set 
structure object. 


Syntax- 

segment-set-processor-not-in-any-segment segment-set-object 


Arguments- 

segment-set-object 

Segment set structure object created by create-segment-set!!. 


Returned Value- 

processor-not-in-any-segment 

Boolean. The value t if this segment set object is not a member 
of any segment in its segment set, and the value nil if not. 


Side Effects 

None. 


Description- 

This is the front-end version of segment-set-processor-not-in-any-segment!!, a 
segment set pvar accessor function. It takes a segment set object, as returned by 
create-segment-set!!, and returns the processor-not-in-any-segment structure 
slot. 
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Examples 

Notes — 


References- 

For information about the components of a segment set structure object, see the 
dictionary entry for create-segment-set!!. 

See also these related segment set operators: 
segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment!! 
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segment-set- [Function] 

processor-not-in-any-segment!! 

Extracts in parallel the contents of the processor-not-in-any-segment slot of the 
supplied segment set pvar. 


Syntax- 

segment-set-processor-not-in-any-segmentM segment-set-pvar 


Arguments- 

segment-set-pvar Segment set pvar, as returned by create-segment-setu. 


Returned Value- 

end-bits-pvar Temporary integer pvar. In each active processor, contains the 
contents of the processor-not-in-any-segment slot of the cor¬ 
responding value of segment-set-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This accessor function returns the contents of the processor-not-in-any-segment 
slot of a segment set pvar, as returned by a call to create-segment-set!!. 
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segment-set-processor-not-in-any-segment!! 


Examples 


Notes 


References- 

For information about the components of a segment set structure pvar, see the dic¬ 
tionary entry for create-segment-set!!. 

See also these related segment set operators: 
segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 
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segment-set-scan!! [Function] 

Within the segment sets defined by the supplied segment set pvar, performs a cumula¬ 
tive reduction operation on the supplied pvar, as with the function scan!!. 

Syntax- 

segment-set-scan!! pvar scan-operator segment-set-pvar 

&key :direction 

:check-for-processors-not-in-segment-set 

:activate-all-processors-in-segment-set 

Arguments- 

pvar Pvar expression. Pvar containing values to be reduced. 

function Two-argument pvar function. Determines type of reduction. 

May be any of +!!, and!!, or!!, logand!!, logior!!, logxor!!, 
max!!, min!!, and copy!!. 

segment-set-pvar Segment set pvar, as returned by create-segment-set!!. De¬ 
termines segments within which scanning takes place. 

direction Either forward or :backward. Determines direction of scan 

through send addresses or across grid. Default is :forward. 

:check-for-processors-not-in-segment-set 

Boolean. Whether to signal an error if segment-set-pvar in¬ 
cludes processors that are not defined to be in any segment. 

:activate-all-processors-in-segment-set 

Boolean. Whether to temporarily bind currently selected set so 
that all processors included in a segment of segment-set-pvar 
are active for duration of scan. 


Returned Value- 

scan-pvar Temporary pvar. A copy of pvar to which the scanning opera¬ 

tion specified by function has been applied. 
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Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

A segment-set-scan !! operation works the same way as the scan!! operation, 
except that it uses segment sets. It performs a specified associative binary *Lisp 
function over the values contained in the processors of each segment. This is done 
as a reduction analogous to the Common Lisp sequence function reduce. The cu¬ 
mulative result of the reduction is stored in each processor within a segment. For 
each segment, the scan operation is reinitiated; results obtained within one seg¬ 
ment are not carried over into the next. 

Unlike scan!!, segment-set-scan!! has no dimension keyword; only scans using 
send address order are presently supported. Also, segment-set-scan!! has no 
:include-self keyword; in a segment-set-scan!! operation each processor always 
receives the result of applying the scan operation to all processors in its segment, 
including itself. 

The pvar argument may be any pvar acceptable to the function specified as the 
function argument. 

The function may be one of the following associative binary parallel functions: 

+!!, and!!, or!!, max!!, min!!, copy!!, logand!!, logior!!, logxor!! 

The segment-set-pvar must be a segment set pvar, as returned by the function 
create-segment-set !!. (See the dictionary entry of create-seg ment-set !! for more 
information.) 

The : direction keyword argument may be given as either forward or :backward 
and defaults to: forward. A forward scan operation is performed in ascending send 
address order. Descending send address order is used if a backward direction is 
specified. 

The :check-for-processors-not-in-segment-set keyword takes a boolean value 
and defaults to nil. If t is specified, segment-set-scan!! checks for processors 
which are in the CSS but which are not included in the segment set. If any are found, 
an error is signaled. If the default is used, the pvar value in processors which are in 
the CSS but which are not included in the segment set are simply ignored. 
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The :activate-all-processors-in-segment-set keyword takes a boolean value and 
defaults to t. If the default is used, all processors in the segment set are activated for 
the duration of the segment-set-scan!! operation. If nil is specified, the scan op¬ 
eration skips the pvar value in any processor that is not in the CSS, regardless of 
whether that processor is included in a segment of the segment set. This can frag¬ 
ment segments by allowing “holes” of deactivated processors. When a scan en¬ 
counters a segment thus fragmented, it ignores any deactivated processors and 
carries the cumulative value of the scan into the next active processor in the seg¬ 
ment. 

Notice that the last option enables scans that operate only in those processors both 
active when the function is entered and inside one of the segments defined by the 
segment set. 

Examples- 

Notes- 


References- 

See also these related segment set operators: 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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segment-set-start-address [Function] 

Returns the contents of the start-address slot of a segment set structure object. 

Syntax- 

segment-set-start-address segment-set-object 

Arguments- 

segment-set-object 

Segment set structure object created by create-segment-set!!. 

Returned Value- 

start-address Integer. Send address of first processor in segment to which 
segment-set-object belongs. 

Side Effects- 

None. 


Description- 

This is the front-end version of segment-set-start-address! !, a segment set pvar 
accessor function. It takes a segment set object returned by create-segment-set!!, 
and returns the contents of the start-address structure slot. 
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Examples 


Notes 


References- 

For information about the components of a segment set structure object, see the 
dictionary entry for create-segment-set!!. 

See also these related segment set operators: 
segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address!! 
segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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segment-set-start-addressM 


segment-set-start-address!! [Function] 

Extracts in parallel the contents of the start-address slot of the supplied segment set 
pvar. 


Syntax- 

segment-set-start-address segment-set-pvar 


Arguments- 

segment-set-pvar Segment set pvar, as returned by create-segment-set!!. 


Returned Value- 

end-address-pvar Temporary integer pvar. In each active processor, contains the 
contents of the start-address slot of the corresponding value of 
segment-set-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This accessor function returns the contents of the start-address slot of a segment 
set pvar, as returned by a call to create-segment-set!!. 
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Examples 


Notes 


References- 

For information about the components of a segment set structure pvar, see the dic¬ 
tionary entry for create-segment-set!!. 

See also these related segment set operators: 
segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits segment-set-start-bits!! 

segment-set-start-address 
segment-set-processor-not-in-any-segment 
segment-set-processor-not-in-any-segment!! 
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segment-set-start-bits [Function] 

Returns the contents of the start-bits slot of a segment set structure object. 

Syntax- 

segment-set-start-bits segment-set-object 

Arguments- 

segment-set-object 

Segment set structure object created by create-segment-setl 1. 

Returned Value- 

start-bits Boolean. The value t if this segment set object is the first in its 

segment, and the value nil if not. 

Side Effects- 

None. 


Description- 

This is the front-end version of segment-set-start-bits! !, a segment set pvar acces¬ 
sor function. It takes a segment set object returned by create-segment-set!!, and 
returns the contents of the start-bits structure slot. 
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Examples 


Notes 


References- 

For information about the components of a segment set structure object, see the 
dictionary entry for create-segment-set!!. 

See also these related segment set operators: 

segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits!! 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 

segment-set-processor-not-in-any-segment!! 
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segment-set-start-bits!! [Function] 

Extracts in parallel the contents of the start-bits slot of the supplied segment set pvar. 


Syntax- 

segment-set-start-bits! ! segment-set-pvar 


Arguments- 

segment-set-pvar Segment set pvar, as returned by create-segment-set!!. 


Returned Value- 

end-bits-pvar Temporary integer pvar. In each active processor, contains the 
contents of the start-bits slot of the corresponding value of seg¬ 
ment-set-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This accessor function returns the contents of the start-bits slot of a segment set 
pvar, as returned by a call to create-segment-set!!. 
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Examples 


Notes 


References- 

For information about the components of a segment set structure pvar, see the dic¬ 
tionary entry for create-segment-set!!. 

See also these related segment set operators: 
segment-set-scan!! 

segment-set-end-bits segment-set-end-bits!! 

segment-set-end-address segment-set-end-address!! 

segment-set-start-bits 

segment-set-start-address segment-set-start-address!! 

segment-set-processor-not-in-any-segment 

segment-set-processor-not-in-any-segment!! 


868 







*Lisp Dictionary 


self!! 


Self!! [Function] 

Returns an address-object pvar containing the NEWS (grid) coordinates of each pro¬ 
cessor. 


Syntax 

self!! 


Arguments- 

Takes no arguments. 


Returned Value- 

address-object-pvar 

Temporary address-object pvar. In each active processor, con¬ 
tains an address object representing the NEWS (grid) coordi¬ 
nates of that processor. 


Side Effects- 

The returned value is allocated on the stack. 


Description- 

This function returns an address object pvar that contains the grid coordinates of 
each processor. It is equivalent to: 

(grid!! (self-address-grid!! (!! 0)) 

(self-address-grid!! (!! 1)) 

(self-address-grid!! (!! n)) 

where n is (1- *number-of-dimensions*). 
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Examples 

Notes — 


References- 

See also the related functions 

enumerate!! rank!! 

self-address!! self-address-grid!! sort!! 

See also the related operations 

address-nth address-nth!! 

address-plus address-plus!! 

address-plus-nth address-plus-nth!! 

address-rank address-rank!! 

grid grid!! 

grid-relative!! 
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self-address!! [Function] 

Returns a pvar containing, in each processor, the send address of that processor. 

Syntax- 

self-address!! 

Arguments- 

Takes no arguments. 

Returned Value- 

self-address-pvar Temporary integer pvar. In each active processor, contains the 
send address of that processor. 


Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a pvar that contains the send address of each selected 
processor. 

Examples- 

An example of a call to self-address!! from top level is the expression 
(ppp (self-address!!) :end 10) 
which displays the following: 

0123456789 
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The self-address! ! function is most commonly used in combination with processor 
selection operators to select a specific subset of processors. For example, 

(ppp (if!! (evenp!! (self-address!!)) 

(! ! 0 ) 

(!! 1)) :end 10) 

0101010101 

More complex selections of processors can be specified by combining the self¬ 
address!! function with mathematical operators such as mod!!. 

(*defvar mod-pvar) 

(*set mod-pvar (mod!! (self-address!!) (!! 4))) 

(ppp mod-pvar :end 14) 

01230123012301 

(ppp (if!! (<! ! mod-pvar (!! 2)) 

(! ! 1 ) 

(!! 0 )) 

:end 14) 

11001100110011 


Notes 


References- 

See also these related operations: 

enumerate!! rank!! self!! 

self-address-grid!! sort!! 

See also these related send and grid address translation operators: 

cube-f rom-grid-address cube-f rom-grid-address!! 

cube-from-vp-grid-address cube-f rom-vp-grid-address!! 

grid-from-cube-address grid-from-cube-address!! 

grid-from-vp-cube-address grid-from-vp-cube-address!! 
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self-address-grid!! [Function] 

Returns a pvar containing in each processor the grid (NEWS) coordinate of that pro¬ 
cessor along a specified dimension. 


Syntax- 

self-address-grid!! dimension-pvar 


Arguments- 

dimension-pvar Integer pvar. Dimension for which the grid (NEWS) coordinate 

of the corresponding processor is determined. 


Returned Value- 

coord-pvar Temporary integer pvar. In each active processor, contains the 

grid (NEWS) coordinate of that processor along the dimension 
specified by dimension-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar that contains the coordinate, along the dimension 
specified by dimension-pvar, of each selected processor. 

The dimension-pvar argument must be a pvar containing a non-negative integer in 
each processor. Each of these integers must be less than the rank of the current VP 
set. 
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Examples- 

Assuming a two-dimensional grid, the expression 

(ppp (self-address-grid!! (!! 0)) :mode :grid :end '(4 4)) 

displays the values 

0 12 3 
0 12 3 
0 12 3 
0 12 3 

and the expression 

(PPP (self-address-grid!! (!! 1)) :mode :grid :end '(4 4)) 

displays the values 

oooo 
1111 
2 2 2 2 
3 3 3 3 

The following code fragment selects the diagonal elements of the grid, 

(*when (=! ! (self-address-grid!! (!! 0)) 
(self-address-grid!! (!! 1))) 

) 


and the following fragment selects the tridiagonal elements of the grid: 


(♦when (or!! 

(=! ! 

(self-address-grid!! 

( ! 

0)) 



(self-address-grid!! 

( ! 

1))) 


( = ! ! 

(self-address-grid!! 

( ! 

0)) 


(1+!! (self-address-grid!! (!! 1)))) 


( = ! ! 


(self-address-grid!! (!! 0)) 


(1-!! (self-address-grid!! (!! 1))))) 


) 
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self-address-grid!! 


Notes- 

Language Note: 

A processor’s grid address is distinct from its send address, even on a one-di¬ 
mensional grid, and there is no guarantee that the two will be the same under 
any circumstances. For example, assuming a one-dimensional grid has been 
defined, the following results might be obtained: 

(ppp (self-address!!) tend 12) 

0123456789 10 11 

(ppp (self-address-grid!! (!! 0)) :end 12) 

3 2 0 1 5 4 6 7 256 255 253 254 


Performance Note: 

The computation of a grid self address using self-address-grid! ! takes a signfi- 
cant amount of time. Rather than calling self-address-grid!! over and over 
again, it is preferable to call it once. For example, the tridiagonal element 
selection example above may be more efficiently written as 

(*let ((x-addr (self-address-grid!! (!! 0))) 

(y-addr (self-address-grid!! (!! 1)))) 

(declare (type (field-pvar *current-send-address-length*) 
x-addr y-addr)) 

(*when (or!! (=!! x-addr y-addr) 

(=!! x-addr (1+!! y-addr)) 

(=!! x-addr (1-!! y-addr))) 


)) 
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References- 

See also these related operations: 

enumerate!! rank!! self!! 

self-address!! sort!! 

See also these related send and grid address translation operators: 

cube-f rom-grid-address cube-f rom-grid-address!! 

cube-f rom-vp-grid-address cube-f rom-vp-grid-address!! 

grid-from-cube-address grid-from-cube-address!! 

grid-from-vp-cube-address grid-from-vp-cube-address!! 
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*S©t [Macro] 

Copies the supplied source pvars into the supplied destination pvars. 


Syntax 


*set 


destination-pvar-1 source-pvar-1 
destination-pvar-2 source-pvar-2 


destination-pvar-n source-pvar-n 


Arguments- 

destination-pvar Pvar expression. Pvar into which values are copied. Must eval¬ 
uate to a non-temporary pvar. 

source-pvar Pvar expression. Pvar from which values are copied. May eval¬ 

uate to any pvar. 

Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

The macro *set evaluates each pair of source-pvar and destination-pvar arguments 
in order. In all active processors, the value of source-pvar is copied into the pvar 
obtained by evaluating destination-pvar. 


Description- 

This macro sets the contents of destination-pvar to the contents of source-pvar in 
all processors of the currently selected set, for each pair of source-pvar and destina¬ 
tion-pvar arguments. Note that both source-pvar and destination-pvar are evalu¬ 
ated. 
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It is an error to attempt to *set the value of a temporary pvar. Temporary pvars are 
returned by *Lisp functions such as !! and +!!. The *Lisp simulator catches this 
error and prints an error message. Neither the *Lisp interpreter nor the *Lisp com¬ 
piler catches this error. 


Examples- 

The following examples show how *set may be used to copy values between pvars: 

(*defvar pvarl (!! 2)) 

(*defvar pvar2 (self-address!!)) 

(*defvar dest) 

;;; set dest to product of pvarl and pvar2 in each processor 
(*set dest (*!! pvarl pvar2)) 

(ppp dest :end 8) 

0 2 4 6 8 10 12 14 

;;; set dest to the value of pvarl in each processor 
;;; where the value of pvar2 is less than 4 
(*when (<!! pvar2 (!! 4)) 

(♦set dest pvarl)) 

(ppp dest rend 8) 

2 2 2 2 8 10 12 14 

As an example of how not to use *set, consider the function foo below. 

(defun foo (x) (*set x (!! 5))) 

These calls to the function foo violate the rule against setting the value of a tempo¬ 
rary pvar, and are therefore in error: 

(foo (!! 3)) 

(foo (cos!! (+!! a b) )) 

To modify array elements and structure pvar slots, use the *setf macro. See the 
dictionary entry for *setf for more information. 
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set 


Notes- 

Important: 

The *set macro evaluates its first argument, as does the Common Lisp set op¬ 
erator. The values contained in this argument, which must be a permanent, 
global, or local pvar, are destructively modified. 


References 
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*setf 


*Setf [Function] 

Destructively modifies the pvars specified by the supplied accessor functions to con¬ 
tain the values specified by the supplied pvar expressions. 


Syntax- 

*setf pvar-accessor-1 pvar-expression-1 
pvar-accessor-2 pvar-expression-2 

pvar-accessor-n pvar-expression-n 


Arguments- 

pvar-accessor *Lisp pvar accessor expression. Indicates pvar to be modified. 
pvar-expression Pvar expression. Value to be stored at the specified location. 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

Destructively modifies the location specified by pvar-accessor to contain the value 
of pvar-expression, for each pair of pvar-accessor and pvar-expression. 


Description- 

This is the *Lisp equivalent of the Common Lisp setf macro. This operation takes 
one or more sets of pvar-accessor and pvar-expression pairs. It evaluates the 
pvar-expression of each pair, and converts the pvar-accessor to an expression that 
modifies the specified location. For each pair, the location referenced by the 
pvar-accessor is modified to contain the value of pvar-expression. The *setf macro 
must be used—and the Common Lisp setf must not be used—to modify locations 
referenced by pvar accessor expressions. 
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Each pvar-accessor must be one of: 

■ a symbol whose value is a pvar, in which case the *setf call behaves like a 
call to *set. 

■ a call to one of the operators 

aref!! sideways-aref!! 

row-major-aref!! row-major-sideways-aref!! 

pref pref!! 

realpart!! imagpart!! 

load-byte!! IdbH 

■ a call to a structure slot accessor defined by *defstruct 

■ a call to a function for which an appropriate modifier has been defined by 
the use of *defsetf. 

■ an expression of the form (the data-type pvar-accessor), where 
pvar-accessor is one of the possible forms listed above 


Examples- 

The operation performed by *setf depends on the type of pvar-accessor to which it 
is applied. For example, a call to *setf such as 

(*setf (pref int-pvar 387) 15) 

changes the value of int-pvar in processor 387 to 15. 

The most common use of *setf is to change the value of pvar array elements and 
pvar structure slots. For example, 

(*setf (aref!! 3by6-array-pvar (!! 2) (!! 5)) (!! 28)) 

changes the value of element 2, 5 of 3by6-array-pvar in each processor to 28. 

(*setf (foo-struct-slotl!! foo-struct-pvar) (!! 84)) 

changes the slotl value of the structure pvar foo-struct-pvar to 84 in each proces¬ 
sor. 
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Accessor forms can be nested, as in the expression 

(*setf (pref (aref!! array-pvar (!! 3)) 29) 100) 

which changes the value of element 3 of array-pvar in processor 29 to 100. Not all 
nestings of operators work, however. For example, the expression 

(*setf (aref (pref array-pvar 29) 3) 100) 

will not perform the same operation as the above example, because the operator 
aref is not one of the parallel accessors that *setf recognizes. 

Notes- 

Usage Note: 

The *setf macro implicitly performs an alias!! operation on array pvar refer¬ 
ences and parallel structure slot accessor forms. It is therefore unnecessary to 
explicitly enclose these types of arguments in calls to alias!!, as in the expres¬ 
sion 

(*setf (alias!! (aref!! array-pvar (!! 3))) (!! 29)) 

which can (and should) be more concisely written as 
(*setf (aref!! array-pvar (!! 3)) (!! 29)) 

See the definition of the alias!! macro for more information. 

Performance Notes: 

Applying *setf to a parallel array reference with nonconstant indices, as in 

(*setf (aref!! array-pvar (random!! (!! 6))) (!! 4)) 

is permitted in the CM-2 implementation of *Lisp, but is relatively inefficient 
compared with applying *setf to references with constant indices, such as 

(*setf (aref!! array-pvar (!! 6)) (!! 4)) 
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On the other hand, using *setf on sideways arrays with non-constant indices is 
an efficient operation. (See the definitions of *sideways-array and sideways- 
aref!! for more information.) 

Also, a call to *setf of the form 

(*setf (pref!! dest-pvar address-pvar) source-pvar) 

is equivalent to a call to *pset of the form 

(*pset :no-collisions source-pvar dest-pvar address-pvar) 

Calling *pset directly in this case is preferred as being more efficient. Using 
*setf on pref!! is equivalent to the *Lisp operation *pset. However, a call to 
pref!! with a :colli$ion-mode argument of :no-collisions takes twice as long as 
a call to *pset, so calling *pset directly is preferable. 

References- 

See also these related operations: 

*defsetf *set *undefsetf 
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set-char-bit!! 


set-char-bit!! 

Sets the state of a single flag bit of the supplied character pvar 
The returned pvar is allocated on the stack. 

Syntax- 

set-char-bit!! character-pvar bit-name-pvar newvalue-pvar 

Arguments- 

character-pvar 
bit-name-pvar 
newvalue-pvar 

Returned Value 

new-char-pvar Temporary character pvar. In each active processor, contains a 

copy of the character in character-pvar with the flag bit speci¬ 
fied by bit-name-pvar set to the value specified by newvalue- 
pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function constructs a copy of character-pvar with the bit-name-pvar bit set to 
newvalue-pvar in each processor. It returns a pvar containing characters that re¬ 
semble those in character-pvar except that the bit-name-pvar bit is set on or off 
depending on the value of the boolean pvar, newvalue-pvar. 


Character pvar. Pvar for which bit selected by bit-name-pvar is 
set. 

Integer pvar. Selects bit to be tested in each active processor. 
Must contain integers in the range 0 to 3 inclusive. 

Boolean pvar. State (set/cleared) to which specified bit is set. 


[Function] 
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The argument character-pvar may be a character pvar, a string-char pvar, or a gen¬ 
eral pvar containing only character or string-char elements. 

The argument bit-name-pvar must be an integer pvar in the range (!! 0) through (!! 
3), inclusive. The same correspondence holds between legal values for the 
bit-name-pvar argument to set-char-bit!! and the Common Lisp control-bit con¬ 
stants as detailed above for char-bit!!. 


Examples- 

(set-char-bit!! (!! #\x) (!! 0) t!!) => (!! Acontrol-x) 

(set-char-bit!! (!! #\control-x) (!! 0) t!!) 

=> (!! #\control-x) 

(set-char-bit!! (!! #\control-x) (!! 0) nil!!) 

=> (!! #\x) 


Notes- 

Unlike its Common Lisp analogue, the argument bit-name-pvar must be an inte¬ 
ger pvar (either an unsigned-byte or a signed-byte pvar). The following correspon¬ 
dence holds between legal values for the bit-name-pvar argument and the recom¬ 
mended Common Lisp control-bit constants: 


Common Lisp 

*Lisp 

: control 

(!! 0) 

:meta 

(!! 1) 

: super 

(!! 2) 

:hyper 

(!! 3) 


References- 

See also the related character pvar attribute operators: 

char-bit!! char-bits!! char-code!! 

char-font!! initialize-character set-char-bit!! 
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set-vp-set [Function] 

Make the specified VP set the current VP set. 

Syntax- 

set-vp-set vp-set 

Arguments- 

vp-set VP set object. VP set to be made current. Must be defined, and 

must be allocated if voidable. 

Returned Value- 

vp-set The supplied vp-set argument is returned. 

Side Effects- 

Sets the value of *current-vp-set* to vp-set. 

Description- 

This function changes the currently selected VP set to vp-set. 

The argument vp-set must be a VP set that is both defined and, in the case of 
flexible VP sets, instantiated. 

The return value of a call to set-vp-set is vp-set. 
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Examples 


Notes 


References- 

See also the following VP set operators: 

create-vp-set deallocate-def-vp-sets 

deallocate-vp-set def-vp-set 

let-vp-set *with-vp-set 
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set-vp-set-geometry [Function] 

Modifies the geometry of a flexible VP set. 


Syntax- 

set-vp-set-geometry vp-set geometry-obj 


Arguments- 

vp-set VP set object. Flexible VP set for which the geometry is altered. 

geometry-obj Geometry object, as returned by create-geometry. Defines 
new geometry of vp-set. 

Returned Value- 

nil Evaluated for side effect only. 

Side Effects- 

The geometry of vp-set is altered to the dimensions specified by geometry-obj. 


Description- 

Modifies the geometry of the specified vp-set, rearranging its values into the con¬ 
figuration specified by geometry-obj. The vp-set argument must be a defined and 
instantiated flexible VP set. 

The parameter geometry-obj must be a geometry object created with create- 
geometry. The number of virtual processors specified by the new geometry must 
be the same as the total number of virtual processors specified by vp-set. 
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Examples- 

(setq geometry-1 (create-geometry tdimensions '(256 256))) 
(setq geometry-2 (create-geometry :dimensions '(65536))) 

(setq vp-set-1 (create-vp-set nil -.geometry geometry-1)) 


(set-vp-set-geometry vp-set-1 geometry-2) 


Notes 


References- 

See also the following flexible VP set operators: 

allocate-vp-set-processors allocate-processors-for-vp-set 

deallocate-vp-set-processors deallocate-processors-for-vp-set 

with-processors-allocated-for-vp-set 

See also the following geometry definition operator: 

create-geometry 

See also the following VP set definition and deallocation operators: 

def-vp-set create-vp-set let-vp-set 
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sf-cross-product!! 


sf-cross-product!! [Function] 

Calculates in parallel the cross product of the supplied single-float vector pvars. 


Syntax- 

sf-cross-product!! vector-pvarl vector-pvar2 


Arguments- 

vector-pvarl, vector-pvarl 

Single-float vector pvars. Pvars for which cross product is com¬ 
puted. 


Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the cross product of the corresponding values of 
vector-pvarl and vector-pvar2. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function calculates the cross product of two single-float vector pvars. 

The arguments vector-pvarl and vector-pvar2 must each be a pvar vector of type 
(pvar (array single-float (3))). That is, the vector stored in each processor of both 
pvar arguments must be of length 3. 

In each processor, the cross product of the two vectors is computed and returned 
as a pvar vector of type (pvar (array single-float (3))). 
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Examples 


Notes- 

Usage note: 

For those familiar with the mathematical notation for cross products, the ac¬ 
tion of sf-cross-product!! may be loosely described as 

vector-pvarl x vector-pvar2 -> sf-result-pvar 

that is, after calling sf-cross-product!!, each element of the returned pvar is 
equal to the cross-product of the corresponding elements of vector-pvarl and 
vector-pvar2. 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+1! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normaH! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normall! 



dsf-vscale-to-unit-vector!! 
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sf-v + -constant!! [Function] 

Adds a single-float scalar pvar to each element of a single-float vector pvar. 


Syntax- 

sf-v+-constant!! vector-pvar scalar-pvar 


Arguments- 

vector-pvar Single-float vector pvar. Vector pvar to which scalar-pvar is 

added. 

scalar-pvar Single-float scalar pvar. Added to each vector element of vec¬ 

tor-pvar. 


Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the result of adding scalar-pvar to each element of the 
vector in vector-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, this function adds the value of the supplied scalar-pvar to each 
element of the vector in vector-pvar, and returns the result as a vector pvar of ele¬ 
ment type single-float. 
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Examples 

Notes — 


References- 

This function is one of a number of vector pvar operators, listed below: 
cross-product!! dot-product!! 

v+!l v-!! v*!! 

vabs!! vabs-squared!! vscale!! 

vscale-to-unit-vector!! *vset-components 

sf-cross-product!! sf-v+-constant!! sf-v—constant!! 

sf-v*-constant!! sf-v/-constant!! sf-vabs!! 

sf-vabs-squared!! sf-vector-normal!! sf-vscale-to-unit-vector!! 

dsf-cross-product!! dsf-vector-normal!! 

dsf-vscale-to-unit-vector!! 
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sf-v—constant!! [Function] 

Subtracts a single-float scalar pvar from each element of a single-float vector pvar. 


Syntax- 

sf-v—constant!! vector-pvar scalar-pvar 


Arguments- 

vector-pvar Single-float vector pvar. Vector pvar from which scalar-pvar is 

subtracted. 

scalar-pvar Single-float scalar pvar. Subtracted from each vector element 

of vector-pvar. 


Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the result of subtracting scalar-pvar from each ele¬ 
ment of the vector in vector-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description-- 

In each processor, this function subtracts the value of the supplied scalar-pvar 
from each element of the vector in vector-pvar, and returns the result as a vector 
pvar of element type single-float. 
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Examples 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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Sf-V*-COnstant!! [Function] 

Multiplies each element of a single-float vector pvar by a single-float scalar pvar. 


Syntax- 

sf-v*-constantl! vector-pvar scalar-pvar 


Arguments- 

vector-pvar Single-float vector pvar. Vector pvar to be multiplied. 

scalar-pvar Single-float scalar pvar. Value by which vector-pvar is multi¬ 

plied. 

Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the result of multiplying each element of the vector in 
vector-pvar by the value in scalar-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, this function multiplies each element of the vector in vector-pvar 
by the value of the supplied scalar-pvar and returns the result as a vector pvar of 
element type single-float. 
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Examples 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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sf-v/-constant!l 


Sf-v/-COnstant!! [Function] 

Divides each element of a single-float vector pvar by a single-float scalar pvar. 


Syntax- 

sf-v/-constant!! vector-pvar scalar-pvar 


Arguments- 

vector-pvar Single-float vector pvar. Vector pvar to be divided by scalar- 

pvar. 

scalar-pvar Single-float scalar pvar. Value by which vector-pvar is divided. 


Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the result of dividing each element of the vector in vec¬ 
tor-pvar by the value in scalar-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

In each processor, this function divi des each element of the vector in vector-pvar by 
the value of the supplied scalar-pvar, and returns the result as a vector pvar of ele¬ 
ment type single-float. 
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Examples 

Notes- 


References- 

This function is one of a number of vector pvar operators, listed below: 
cross-product!! dot-product!! 

v+!! v-!! v*!! 

vabs!! vabs-squared!! vscale!! 

vscale-to-unit-vector!! *vset-components 

sf-cross-product!! sf-v+-constant!! sf-v—constant!! 

sf-v*-constant!! sf-v/-constant!! sf-vabs!! 

sf-vabs-squared!! sf-vector-normal!! sf-vscale-to-unit-vector!! 

dsf-cross-product!! dsf-vector-normal!! 

dsf-vscale-to-unit-vector!! 
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sf-vabs!! 


Sf-vabS!! [ Function ] 

Calculates in parallel the vector magnitude of the supplied single-float vector pvar. 


Syntax- 

sf-vabs!! vector-pvar 


Arguments- 

vector-pvar Single-float vector pvar. Pvar for which vector magnitude is 

computed. 

Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the vector magnitude of the corresponding value of 
vector-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the single float analogue of vabs!!. 

(sf-vabs!! sf-vector-pvar) <=> 

(sqrt!! (sf-vabs-squared!! sf-vector-pvar)) <=> 

(sqrt!! (sf-dot-product!! sf-vector-pvar sf-vector-pvar)) 
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sf-vabs!! 


Examples- 

Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a number of vector pvar operators, listed below: 

cross-product!! dot-product!! 

v+!! v-!! v*!! 

vabs!! vabs-squared!! vscale!! 

vscale-to-unit-vector!! *vset-components 

sf-cross-product!! sf-v+-constant!! sf-v—constant!! 

sf-v*-constant!! sf-v/-constant!! sf-vabs!! 

sf-vabs-squared!! sf-vector-normal!! sf-vscale-to-unit-vector!! 

dsf-cross-product!! dsf-vector-normal!! 

dsf-vscale-to-unit-vector!! 
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sf-vabs-squared!! 


sf-vabs-squared!! [Function] 

Calculates in parallel the squared magnitude of the supplied single-float vector pvar. 


Syntax- 

sf-vabs-squared!! vector-pvar 


Arguments- 

vector-pvar Single-float vector pvar. Pvar for which squared magnitude is 

computed. 


Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the squared magnitude of the corresponding value of 
vector-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the single float analogue of vabs-squared!!. 

(sf-vabs-squared!! sf-vector-pvar) <=> 
(sf-dot-product!! sf-vector-pvar sf-vector-pvar) 
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Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+M 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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sf-vector-normal!! 


sf-vector-normal!! [Function] 

Calculates in parallel the normalized cross product of the supplied single-float vector 
pvars. 


Syntax- 

sf-vector-normal!! vector-pvarl vector-pvar2 


Arguments- 

vector-pvarl, vector-pvar2 

Single-float vector pvars. Pvars for which normalized cross 
product is computed. 


Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the normalized cross product of the corresponding 
values of vector-pvarl and vector-pvar2. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function calculates in parallel the normalized cross product of two single-float 
vector pvars, and is equivalent to 

(sf-vscale-to-unit-vector!! 

(sf-cross-product!! vector-pvarl vector-pvar2)) 

The arguments vector-pvarl and vector-pvar2 must each be a pvar vector of type 
(pvar (array single-float (3))). That is, the vector stored in each processor of both 
pvar arguments must be of length 3. 
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Examples-- 

Notes- 

Usage note: 

The orientation of the normalized cross product produced in each processor 
depends on the order of the vector-pvar arguments. Specifically, 

(*set vl (sf-vector-normal vector-pvarl vector-pvar2)) 

(*set v2 (sf-vector-normal vector-pvar2 vector-pvarl)) 

vl <=> (sf-v*-constant v2 (!! -1)) 
that is, vl is the vector negative of v2. 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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sf-vscale-to-unit-vector!! 


Sf-VSCale-tO-unit-vector!! [Function] 

Calculates in parallel the result of scaling the supplied single-float vector pvar to unit 
length. 


Syntax- 

sf-vscale-to-unit-vector! ! vector-pvar 


Arguments- 

vector-pvar Single-float vector pvar. Vector pvar to be scaled. 


Returned Value- 

sf-result-pvar Temporary single-float vector pvar. In each active processor, 
contains the result of scaling the value of vector-pvar to a unit- 
length vector. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the single float analogue of vscale-to-unit-vector!!. It is 
equivalent to the following operation: 

(sf-vscale!! vector-pvar (/!! (sf-vabs!! vector-pvar))) 
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Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+M 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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sideways-aref!! 


sideways-aref!! [Function] 

Performs a parallel array reference on the supplied sideways array pvar. 


Syntax- 

sideways-aref!! array-pvar &rest subscript-pvars 


Arguments- 

array-pvar Array pvar from which values are referenced. Must have been 

turned sideways by * sideways-array or ‘slicewise. 

subscript-pvars Integer pvars. Specify array element to be referenced in each 
processor. 


Returned Value- 

value-pvar Temporary pvar. Value retrieved in each processor. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function performs a parallel array reference, similar to a ref !!, on an array that 
has been turned sideways by * sideways-array or *slicewise. In general, especially 
for large arrays, non-constant indexing can be very slow. Turning arrays sideways 
allows the CM-2 architecture to do non-constant indexing in constant time. 
However, sideways arrays can only be referenced by using sideways-aref!!. 

One subscript-pvar argument must be given for each dimension of array-pvar. Each 
subscript-pvar must contain non-negative integers within the range of indices for 
that dimension. 
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Examples- 

These expressions declare and define an array pvar that can be turned sideways. In 
each processor, the vector [ 5.0 8.0 ] is stored. 

[ 3.0 0.0 ] 

(♦proclaim '(type (array-pvar single-float '(2 2)) 
my-sideways-array)) 

(*defvar my-sideways-array (!! #2A((5.0 8.0) (3.0 0.0)))) 

The array is turned sideways, and is verified to be slicewise. 

(♦sideways-array my-sideways-array) 

(sideways-array-p my-sideways-array) => T 

The following expression defines two pvars containing non-constant indices, and 
then uses sideways-aref!! to perform a parallel array reference on the array pvar 
my-sideways-array. 

(♦let ((index-1 (mod!! (self-address!!) (!! 2)))) 

(index-2 (mod!! (floor!! (self-address!!) (!! 2)) 

(!! 2 )))) 

(PPP (sideways-aref!! my-sideways-array 

index-2 index-1) 

:end 14)) 

5.0 8.0 3.0 0.0 5.0 8.0 3.0 0.0 5.0 8.0 3.0 0.0 5.0 8.0 

The above example uses mod!! for clarity. It can also be written as: 

(♦let ((index-1 (load-byte!! (self-address!!) (!! 0) (!! 1))) 
(index-2 (load-byte!! (self-address!!) (!! 1) (!! 1)))) 
(ppp (sideways-aref!! my-sideways-array 

index-2 index-1) 

:end 14)) 
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sideways-aref!! 


The sideways-arefl! function may also be used with *setf to modify the values 
stored in a sideways array. For example, given the following declarations 

(♦proclaim "(type (array-pvar single-float "(2)) 
my-sideways-array)) 

(*defvar my-sideways-array (!! #(5.0 0.0))) 

this example demonstrates the use of *setf to store values into an array pvar using 
constant indices: 

(*setf (sideways-aref!! my-sideways-array (!! 1)) (!! 6.0)) 

(ppp (sideways-aref!! my-sideways-array 

(mod!! (self-address!!) (!! 2))) 

:end 14) 

5.0 6.0 5.0 6.0 5.0 6.0 5.0 6.0 5.0 6.0 5.0 6.0 5.0 6.0 

and this example shows the use of *setf with non-constant indices. 

(*setf (sideways-aref!! my-sideways-array 

(mod!! (self-address!!) (!! 2))) 

(! ! 7.0)) 

(PPP (sideways-aref!! my-sideways-array (!! 0)) rend 14) 

7.0 6.0 7.0 6.0 7.0 6.0 7.0 6.0 7.0 6.0 7.0 6.0 7.0 6.0 

(ppp (sideways-aref!! my-sideways-array (!! 1)) :end 14) 

5.0 7.0 5.0 7.0 5.0 7.0 5.0 7.0 5.0 7.0 5.0 7.0 5.0 7.0 

Note that the result of the second example depends on the result of the first. 
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Notes- 

The sideways-aref! ! function works in the same way as aref !! does except that it is a 
special accessor defined to operate on sideways arrays only. Requiring this distinc¬ 
tion allows the *Lisp compiler to generate efficient code to reference sideways ar¬ 
rays without requiring declarations that identify arrays as being sideways. 

There are some important restrictions on the size of arrays passed as arguments to 
sideways-aref!!. The array-pvar argument must be an array pvar that has been 
turned sideways. Arrays that have been turned sideways must contain elements 
whose lengths are powers of 2 or multiples of 32. Further, the total number of bits 
the sideways array occupies in CM memory must be divisible by 32. This number 
can be determined either by (pvar-length array-pvar) or by multiplying the total 
number of elements in the array by the size of an individual element. 


References- 

See also the related array-referencing operations: 

aref!! row-major-aref!! 

row-major-sideways-aref!! 

The following operations convert arrays to and from sideways orientation: 

"processorwise *sideways-array *slicewise 

See the definition of the * sideways-array operation for more information about 
sideways arrays. 
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* sideways-array 


*sideways-array [Function] 

Toggles an array between processorwise and sideways (slicewise) orientations. 


Syntax- 

* sideways-array array-pvar 


Arguments- 

array-pvar Array pvar to be converted. 


Returned Value- 

t Evaluated for side effect only. 


Side Effects- 

Converts array-pvar to sideways orientation if it is in normal orientation. Converts 
array-pvar back to normal orientation if it is in sideways orientation. 


Description- 

The function * sideways-array forces array-pvar to be addressed in a sideways 
(slicewise) ordering. Calling * sideways-array on an array that is already sideways 
returns it to a processorwise ordering. 


Examples- 

The following example shows how one might use slicewise arrays. Given the vector 
pvar defined by 

(*proclaim '(type (vector-pvar single-float 20) 
my-sideways-vector)) 

(*defvar my-sideways-vector 

(make-array!! 20 :element-type 'single-float-pvar)) 
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the following code example calls a user-defined function to fill my-sideways- 
vector with data, uses * sideways-array to turn it sideways so that it can be ac¬ 
cessed using indirect addressing, calls another user-defined function to operate on 
the sideways vector pvar, and finally uses * sideways-array again to return it to pro- 
cessorwise orientation, so that its values can be accessed and displayed. 

(defun main () 

(fill-my-sideways-vector-with-values) 

(♦sideways-array my-sideways-vector) 
(do-computations-on-my-sideways-vector) 

(♦sideways-array) 

(ppp my-sideways-vector :end 10)) 


Notes- 

Implementation Note: 

Turning an array sideways (slicewise) allows the CM-2 hardware to more efficiently 
reference arrays using indirect addressing. On the CM-2, indirect addressing is 
array referencing in which a different array element is accessed in each processor. 

Usage Notes: 

There are some important restrictions on the size of arrays passed as arguments to 
*sideways-array. These restrictions extend to the related functions 
*processorwise and * slicewise. 

The array-pvar argument must be an array pvar that contains elements whose 
lengths are powers of 2 or multiples of 32. Further, the total number of bits the 
array occupies in CM memory must be divisible by 32. This number can be deter¬ 
mined either by (pvar-length array-pvar) or by multiplying the total number of 
elements in the array by the size of an individual element. 

The * sideways-array function is most efficient when the array elements of array- 
pvar are each 32 bits long. 


References- 

See also the functions *proce$sorwise, sideways-aref!!, sideways-array-p, and 
*slicewise. 
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sideways-array-p [Function] 

Tests whether the supplied array is currently in sideways (slicewise) orientation. 

Syntax- 

sideways-array-p array-pvar 

Arguments- 

array-pvar Array pvar. Pvar to be tested for sideways orientation. 

Returned Value- 

sideways-array-p Boolean. The value t if array-pvar is in sideways (slicewise) 
orientation, and the value nil if it is in normal orientation. 

Side Effects- 

None. 


Description- 

Tests the specified array pvar, returning t if it is sideways (slicewise) and nil other¬ 
wise. 

Turning an array sideways, via one of the functions *sideways-array, *slicewise, or 
•processorwise, allows special Connection Machine hardware to more efficiently 
reference arrays using indirect addressing. On the CM, indirect addressing is 
array referencing in which a different array element is accessed in each processor. 
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Examples- 

Notes- 

References- 

For more information on giving an array pvar a sideways orientation, see the dic¬ 
tionary entries for *processorwise, *sideways-array, and ‘slicewise. 


916 



*Lisp Dictionary 


signum!! 


signum!! [Function] 

Returns a pvar indicating the sign of the supplied pvar. 


Syntax- 

signum !! numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Pvar for which sign is determined. 


Returned Value- 

signum-pvar Temporary integer pvar. In each active processor, contains ei¬ 
ther 1,0, or -1 depending on whether the value of numeric-pvar 
is positive, zero, or negative, respectively. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a pvar containing -1, 0, or 1 in each processor according to 
whether the value of numeric-pvar in that processor is negative, zero, or positive. 
For a floating-point pvar, the result is a floating-point pvar of the same format. 


917 



signum!! *Lisp Dictionary 

Examples- 

Notes- 

References- 
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Sin!! [Function] 

Takes the sine of the supplied pvar. 

Syntax- 

sin !! radians-pvar 

Arguments- 

radians-pvar Numeric pvar. Angle, in radians, for which the sine is calcu¬ 
lated. 

Returned Value- 

sine-pvar Temporary numeric pvar. In each active processor, contains 

the sine of the corresponding value of radians-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

The function sin!! returns the sine of its argument in each processor. 
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Examples - 

Notes- 

References 
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sinh!! 


sinh!! 

Takes the hyperbolic sine of the supplied pvar. 

Syntax- 

sinh !! radians-pvar 

Arguments- 

radians-pvar Numeric pvar. Angle, in radians, for which the hyperbolic sine 
is calculated. 


[Function] 


Returned Value- 

sinh-pvar Temporary numeric pvar. In each active processor, contains 

the hyperbolic sine of the corresponding value of radians-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a temporary pvar whose value in each processor is the hyper¬ 
bolic sine of the value in numeric-pvar. 
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sinh!! 

Examples - 

Notes- 

References 
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*slicewise [*Defun] 

Converts a normal, processorwise array to sideways (slicewise) orientation. 


Syntax- 

* slicewise array-pvar 


Arguments- 

array-pvar Array pvar. Normal orientation array pvar to be converted. 


Returned Value- 

t Evaluated for side effect only. 


Side Effects- 

Converts array-pvar from normal orientation to sideways orientation. 


Description- 

Converts a normal, processorwise array to slicewise (sideways) orientation. 

The array-pvar parameter must be a normal, processorwise array. If array-pvar is 
already slicewise (sideways), an error is signaled. 

Turning an array sideways allows special Connection Machine hardware to more 
efficiently reference arrays using indirect addressing. On the CM, indirect ad¬ 
dressing is array referencing in which a different array element is accessed in each 
processor. 
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Examples 


Notes- 

The function *slicewise is equivalent to a call to *sideways-array with an array 
argument that is in normal, processorwise orientation. 

There are some important restrictions on the size of arrays passed as arguments to 

"slicewise. 

The array-pvar argument must be an array pvar that contains elements whose 
lengths are powers of 2 or multiples of 32. Further, the total number of bits the 
array occupies in CM memory must be divisible by 32. This number can be deter¬ 
mined either by (pvar-length array-pvar) or by multiplying the total number of 
elements in the array by the size of an individual element. 

The * slicewise function is most efficient when the array elements of array-pvar are 
each 32 bits long. 


References- 

See also the functions * processorwise, * sideways-array, and sideways-array-p. 
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some!! [Function] 

Tests in parallel whether the supplied pvar predicate is true for at least one set of ele¬ 
ments having the same indices in the supplied sequence pvars. 


Syntax- 

some!! predicate sequence-pvar &rest sequence-pvars 


Arguments- 

predicate Boolean pvar predicate. Used to test elements of sequences in 

the sequence-pvar arguments. Must take as many arguments as 
the number of sequence-pvar arguments supplied. 

sequence-pvar, sequence-pvars 

Sequence pvars. Pvars containing, in each processor, 
sequences to be tested by predicate. 


Returned Value- 

some-pvar Temporary boolean pvar. Contains the value t in each active 

processor in which at least one set of elements having the same 
indices in the sequences of the sequence-pvars satisfies the 
predicate. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The some!! function returns a boolean pvar indicating in each processor whether 
the supplied predicate is true for at least one set of elements with the same indices 
in the sequences of the supplied sequence-pvars. 
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In each processor, the predicate is first applied to the index 0 elements of the 
sequences in the sequence-pvars, then to the index 1 elements, and so on. The nth 
time predicate is called, it is applied to the nth element of each of the sequences. If 
predicate returns t in any processor, that processor is temporarily removed from 
the currently selected set for the remainder of the operation. The operation contin¬ 
ues until the shortest of the sequence-pvars is exhausted, or until no processors 
remain selected. 

The pvar returned by some! ! contains t in each processor where predicate returns 
the value t for at least one set of sequence elements. If predicate returns nil for every 
set of sequence elements in a given processor, some! ! returns nil in that processor. 


Examples 


(some! ! 

'equalp!! ( 

! #(1 

2 

3)) ( 

! #(1 

2 

3))) 

<=> 

t! ! 

(some! ! 

"equalp!! ( 

! #(1 

2 

3)) ( 

! #(1 

2 

6))) 

A 

II 

V 

t! ! 

(some! ! 

'equalp!! ( 

! #(1 

2 

3)) ( 

! #(1 

2 

3 4))) 

<=> 

t! ! 

(some! ! 

'equalp!! ( 

! #(1 

2 

3)) ( 

! # (2 

6 

9))) 

<=> 

nil! 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See the related functions every!!, notany!!, and notevery!!. 
See also the general mapping function amap!!. 


926 






*Lisp Dictionary 


sort!! 


Sort!! [Function] 

Performs a parallel sort on the values of the supplied pvar. 

Syntax- 

sort!! pvar predicate &key :dimension :segment-pvar :key 


Arguments- 

numeric-pvar Non-complex numeric pvar. Pvar containing values to be 
sorted. 

predicate Two-argument pvar predicate. Determines type of sort. Cur¬ 

rently limited by implementation to the function <=!!. 

dimension Integer or nil. Specifies dimension along which to perform 

ranking. The default, nil, specifies a send-address order rank¬ 
ing. If not nil, this argument must be an integer between 0 inclu¬ 
sive and *number-of-dimensions* exclusive. 

:segment-pvar Segment pvar or nil. Specifies segments in which to perform 
sort. The default, nil, specifies an unsegmented sort. 

:key One-argument pvar function. Applied to pvar before sort is 

performed. 

Returned Value- 

sort-pvar Temporary pvar. In all active processors, contains the values of 

pvar sorted into the order specified by predicate. 

Side Effects- 

The returned pvar is allocated on the stack. 
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Description- 

In all active processors, sort!! sorts the values of the supplied pvar. 

The keywords, :dimension and :segment-pvar permit rankings to be taken along 
specific grid dimensions and within segments. 

The dimension keyword specifies whether the sorting is done by send address or¬ 
der or along a specific dimension. If a dimension is specified, sorting is performed 
only along that dimension. The default value, nil, specifies a send-address order 
sort. 

For example, assuming a two-dimensional grid, a: dimension argument of 0 causes 
sorting to occur independently in each “row” of processors along dimension 0. A 
: dimension argument of 1 causes sorting to occur independently in each “column” 
of processors along dimension 1 (see Figure 4). 


DIMO 


DIM 


0 
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8 

12 

1 

5 

9 

13 

2 

6 

10 

14 

3 

7 

11 

15 


DIMO 


DIMO 


DIM - -j— 

w —“ 


DIM I , ... 

‘Iff4 


(self-address!!) 


:dimension 0 


:dimension 1 


Figure 4. Effect of different :dimension arguments, 
assuming a two-dimensional grid 


The :segment-pvar argument specifies whether sorting is performed separately 
within segments. The default is nil; sort!! is by default unsegmented. If provided, 
the :segment-pvar value must be a segment pvar. A segment pvar contains 
boolean values, t in the first processor of each segment and nil in all other proces¬ 
sors. If a segment pvar is specified, then sorting is done independently within each 
segment. 

If both a :dimension and a :segment pvar argument are specified, then the sort is 
done independently for each “row” along the specified dimension and independ¬ 
ently within segments for each row. 
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The: key argument allows selection of a key on which the sort is done. For instance, 
a *defstruct (parallel structure) slot accessor function could be provided as the 
:key argument and a pvar of the associated *defstruct type could be supplied as 
the pvar argument. A sort!! with these arguments would sort the values of the 
supplied pvar based on the value of the accessed slot in each processor. 

Examples- 

A sample call to sort!! is 

(sort!! numeric-pvar) 

Assume that numeric-pvar contains the following values, with * standing for an 
unselected processor: 

7 * 2 3 * 1 0 6 ... 

Assuming that all other active processors contain values greater than those shown 
here, the result of the above call to sort!! is a pvar containing the values 

0*12*367... 

Notice that data in unselected processors remains unchanged. 

A sample call to sort!! with a :segment-pvar argument is 

(sort!! data-pvar '<=!! 

:segment-pvar (evenp!! (self-address!!))) 

If data-pvar contains the values 

02421753478 2... 

then (again assuming that all other processors contain larger values than those 
shown here) the returned pvar would contain the values 

0224 17354728... 
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An example of sort!! with a '.dimension argument is 

(sort!! data-pvar '<=!! :dimension 1) 

Assuming the two-dimensional VP set geometry defined by 

(♦cold-boot :initial-dimensions '(4 4)) 

if the expression 

(ppp data-pvar :mode :grid) 

displays the values 

10 1 11 13 

8 15 9 6 

5 3 2 7 

4 12 0 14 

then the expression 

(PPP (sort!! (self-address!!) '<=!! :dimension 1) :mode :grid) 
will display the values 

4 10 6 

5 3 2 7 

8 12 9 13 

10 15 11 14 

A sample call to sort!! with a :key argument is 

(sort!! foo '<=!! dimension 0 :key 'foo-a!!) 

If too is an instance of a *defstruct parallel structure with a slot named foo-a!!, 
then this expression sorts foo based on the value of the a slot in each processor. 
Also, because the -.dimension argument is 0, the sort takes place independently for 
each coordinate along dimension 0. 
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Notes- 

The sort performed by sort!! is not guaranteed to be stable. If numeric-pvar con¬ 
tains the same value in two or more active processors, the order in which these 
values are returned in rank-pvar is arbitrary and indeterminate. 

References- 

See also the related functions 

enumerate!! rank!! self!! 

self-address!! self-address-grid!! 
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spread!! [Function] 

Spreads values of a pvar from one coordinate of a grid dimension to all coordinates 
along that dimension. 


Syntax- 

spread!! pvar dimension coordinate 


Arguments- 

pvar Pvar expression. Pvar containing values to be spread. 

dimension Integer or nil. Index, zero-based, of dimension along which val¬ 

ues are spread. If nil, a send-address order spread is per¬ 
formed, and coordinate specifies a send address. 

coordinate Integer. Coordinate along dimension from which to spread val¬ 

ues. 


Returned Value- 

spread-pvar Temporary pvar, of same type as pvar. Contains the result of 

spreading the values of pvar from the specified coordinate of 
the grid dimension specified by dimension to all processors 
along the length of the dimension. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function spreads data across the Connection Machine processors along di¬ 
mension dimension. The data is taken from the processor at the specified coordi¬ 
nate and spread to all active processors along the specified dimension. 

(See Figure 5.) 
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DIMO 
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Figure 5. Effect of different dimension arguments, 
assuming a two-dimensional grid 


It is an error if coordinate specifies any processors that are not in the currently 
selected set. 


Examples- 

Assuming a two-dimensional grid, and a pvar, numeric-pvar, containing the 
values 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 


then the expression 

(spread!! numeric-pvar 0 2) 
returns a pvar containing the values 


3 

3 

3 

3 

3 

8 

8 

8 

8 

8 

13 

13 

13 

13 

13 

18 

18 

18 

18 

18 

23 

23 

23 

23 

23 
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Notes- 

Performance Note: 

The expression 

(! ! (pref x 10)) 

can be used to spread data to all processors faster than the equivalent, but less 
efficient expression 

(spread!! x nil 10) 

which performs a send-address spread of data across all active processors. 

References- 

See also these related operations: 

reduce-and-spread!! scan!! segment-set-scan!! 
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sqrt! ! [Function] 

Takes the square root of the supplied numeric pvar 


Syntax- 

sqrt!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Pvar for which the square root is calculated. 


Returned Value- 

sqrt-pvar Numeric pvar. In each active processor, contains the non-nega¬ 

tive square root of the corresponding value of numeric-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This returns the non-negative square root of its argument, if the argument is not 
complex. If the argument is complex, the principal square root is returned. Unlike 
Common Lisp, it is an error to provide a negative non-complex value to sqrt!!. 

The non-negative square root of numeric-pvar is returned. 
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Examples 


Notes- 

The function sqrt!! will never return a complex pvar as its result unless numeric- 
pvar is complex, or is coerced into complex form by use of the functions complex!! 
or coerce! !, as shown below. It is an error if the argument numeric-pvar is a non¬ 
complex pvar that contains negative values. 

(sqrt!! (coerce!! (!! -1) '(pvar (complex single-float)))) 

<=> 

(sqrt!! (complex!! (!! -1))) 

<=> 

(!! #c(0.0 1.0)) 


References 
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standard-char-p!! [Function] 

Performs a parallel test for standard characters on the supplied pvar. 


Syntax- 

standard-char-p!! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for standard characters. 


Returned Value- 

standard-charp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is 
an character of type standard-char. Contains nil in all other 
processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns t in those processors where character-pvar contains an ele¬ 
ment of type standard-char; it returns nil elsewhere. The Common Lisp definition 
of standard-char is used, i.e., a standard character is a character with zero bits and 
font attributes, that is defined as part of the Common Lisp standard character set. 
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Examples - 

Notes- 

References 
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String-char-p!! [Function] 

Performs a parallel test for string characters on the supplied pvar. 


Syntax- 

string-char-p!! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for string characters. 


Returned Value- 

standard-charp-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is 
an character with bits and font attributes equal to zero. Con¬ 
tains nil in all other processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns t in those processors where character-pvar contains string- 
char data and nil in processors where character-pvar contains character data. 
Characters of type string-char have zero bits and font attributes. 
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Examples 


Notes 


References- 

See also these related pvar data type predicates: 

booleanp!! characterp!! 

floatp.M front-end-p!! 

numberp!! structurep!! 


complexp!! 

integerp!! 

typepM 
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structurep!! 

Tests whether the supplied pvar is a structure pvar. 

Syntax- 

structurep!! pvar 

Arguments- 

pvar Pvar expression. Pvar to be tested. 

Returned Value- 

structurep-pvar A temporary pvar equal to t!! if pvar is a structure pvar, and 
nil!! otherwise. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function returns a boolean pvar with the value t!! if pvar is a structure pvar and 
nil!! if not. 


[Function] 
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Examples 


Notes 


References- 

See also these related pvar data type predicates: 

booleanp!! characterp!! complexp!! 

floatp!! front-end-p!! integerp!! 

numberp!! string-char-p!! typep!! 
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subseq !! [ Function ] 

Extracts a subsequence in parallel from the supplied sequence pvar. 

Syntax- 

subseq!! sequence-pvar start &optional end 

Arguments- 

sequence-pvar Sequence pvar. Pvar from which subsequence is extracted. 

start Integer pvar. Index, zero-based, of start of sequence to extract. 

Must contain identical values in all active processors. 

end Integer pvar. Index, zero-based, of end of sequence to extract. 

Must contain identical values in all active processors. 

Returned Value- 

subseq-pvar Sequence pvar. In each active processor, contains the subse¬ 

quence of sequence-pvar specified by start and end. 

Side Effects- 

The returned value is allocated on the stack. 


Description-- 

This function returns, in each processor, a sequence pvar of the same type as 
sequence-pvar and of length (-!! end start). The resulting sequence pvar contains a 
copy of the values of the elements found in sequence-pvar. 

The argument sequence-pvar must be a sequence pvar. The arguments start and 
end must be non-negative integer pvars within the range of indices for sequence- 
pvar. Unlike most of the other sequence pvar operations, both start and end must 
contain uniform values in all active processors. Thus, the value of (-!! end start) 
must be the same across all active processors. 
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/ 

\ 

Examples- 

(setq abed (typed-vector!! '(pvar character) 

(! ! #\A) (!! #\B) (!! #\C) (!! #\D))) 

(setq be (subseq!! abed (!! 1) (!!2)) 

(ppp (aref!! be (!! 0) (!! 1)) :end 3) 

=>#\B #\C #\B #\C #\B #\C 


Notes 


Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

See also these related *Lisp sequence operators: 

copy-seq!! Mill length!! 

*nreverse reduce!! reverse!! 

See also the generalized array mapping functions amap!! and *map. 
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substitute!! [Function] 

Performs a parallel substitution operation on the supplied sequence pvar, replacing 
specified old items with new items. 


Syntax 


substitute!! 


new-item old-item sequence-pvar 

&key :from-end :test :test-not 
:start :end :count :key 


Arguments 


new-item Pvar expression, of same data type as sequence-pvar. Item to 

substitute for old-item in each processor. 

old-item Pvar expression, of same data type as sequence-pvar. Item to be 

replaced in each processor. 

sequence-pvar Sequence pvar. Pvar containing sequences to be modified. 

:from-end Boolean pvar. Whether to begin substitution from end of se¬ 

quence in each processor. 

:test Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eqi!!. 

:test-not Two-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a nil result. 

: start Integer pvar. Index of sequence element at which substitution 

starts in each processor. If not specified, search begins with 
first element. Zero-based. 

:end Integer pvar. Index of sequence element at which substitution 

ends in each processor. If not specified, search continues to 
end of sequence. Zero-based. 

: count Integer pvar. Maximum number of replacements to perform in 

each processor. Defaults to (length!! sequence-pvar) 
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:key One-argument pvar accessor function. Applied to 

sequence-pvar before search is performed. 


Returned Value- 

substitute-pvar Temporary sequence pvar. In each active processor, contains a 
copy of the sequence from sequence-pvar with each element 
matching old-item replaced by new-item. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp substitute function. 

In each processor, the substitute!! function searches sequence-pvar for elements 
that match old-item. The function returns a copy of sequence-pvar with each 
matching sequence element modified to contain the value specified by new-item. 

Elements of sequence-pvar are tested against old-item with the eql!! operator un¬ 
less another comparison operator is supplied as either of the -.test or :test-not ar¬ 
guments. The keywords :test and :test-not may not be used together. A lambda 
form that takes two pvar arguments and returns a boolean pvar result may be 
supplied as either the :test and :test-not argument. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 

The : count keyword argument must be a positive integer pvar with values less than 
or equal to (length !! sequence-pvar). In each processor at most count elements are 
substituted. 
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Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 

count!! count-if!! count-if-not!! 

find!! find—if!! find—if—not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position—if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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substitute-if!! [Function] 

Performs a parallel substitution operation on the supplied sequence pvar, replacing 
items that satisfy the supplied test with new items. 


Syntax- 

substitute-if!! new-item test sequence-pvar 

&key :from-end :start :end :count :key 


Arguments- 

new-item Pvar expression, of same data type as sequence-pvar. Item to 

substitute for elements satisfying test in each processor. 

test One-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

sequence-pvar Sequence pvar. Pvar containing sequences to be modified. 

:from-end Boolean pvar. Whether to begin substitution from end of se¬ 

quence in each processor. 

Integer pvar. Index of sequence element at which substitution 
starts in each processor. If not specified, search begins with 
first element. Zero-based. 

Integer pvar. Index of sequence element at which substitution 
ends in each processor. If not specified, search continues to 
end of sequence. Zero-based. 

Integer pvar. Maximum number of replacements to perform in 
each processor. Defaults to (length!! sequence-pvar) 

One-argument pvar accessor function. Applied to 
sequence-pvar before search is performed. 


: start 


:end 


: count 

:key 
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Returned Value- 

substitute-pvar Temporary sequence pvar. In each active processor, contains a 
copy of the value of sequence-pvar with each item satisfying test 
replaced by new-item. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description-- 

This function is the parallel equivalent of the Common Lisp substitute-if function. 

In each processor, the function substitute-if! ! searches sequence-pvar for elements 
satisfying test. The function returns a copy of sequence-pvar with each matching 
sequence element modified to contain the value specified by new-item. A lambda 
form that takes a single pvar argument and returns a boolean pvar result may be 
supplied as the test argument. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 

The: count keyword argument must be a positive integer pvar with values less than 
or equal to (length !! sequence-pvar). In each processor at most count elements are 
substituted. 


Examples 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a group of similar sequence operators, listed below: 
count!! count-ifl! count-if-not!! 

find!! find-if!! find-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position-if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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substitute-if-not!! [Function] 

Performs a parallel substitution operation on the supplied sequence pvar, replacing 
items that fail the supplied test with new items. 


Syntax- 

substitute-if-not!! new-item test sequence-pvar 

&key :from-end :start :end :count :key 


Arguments- 

new-item Pvar expression, of same data type as sequence-pvar. Item to 

substitute for elements failing test in each processor. 

test One-argument pvar predicate. Test used in comparisons. Indi¬ 

cates a match by returning a non-nil result. Defaults to eql!!. 

sequence-pvar Sequence pvar. Pvar containing sequences to be modified. 

:from-end Boolean pvar. Whether to begin substitution from end of se¬ 

quence in each processor. 

: start Integer pvar. Index of sequence element at which substitution 

starts in each processor. If not specified, search begins with 
first element. Zero-based. 

: end Integer pvar. Index, of sequence element at which substitution 

ends in each processor. If not specified, search continues to 
end of sequence. Zero-based. 

: count Integer pvar. Maximum number of replacements to perform in 

each processor. Defaults to (length!! sequence-pvar) 

:key One-argument pvar accessor function. Applied to 

sequence-pvar before search is performed. 
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Returned Value- 

substitute-pvar Temporary sequence pvar. In each active processor, contains a 
copy of the value of sequence-pvar with each item failing test 
replaced by new-item. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel equivalent of the Common Lisp substitute-if-not 
function. 

In each processor, the function substitute-if-not! ! searches sequence-pvar for ele¬ 
ments failing test. The function returns a copy of sequence-pvar with each matching 
sequence element modified to contain the value specified by new-item. A lambda 
form that takes a single pvar argument and returns a boolean pvar result may be 
supplied as the test argument. 

The :key keyword accepts a user-defined function used to extract a search key 
from sequence-pvar. This key function must take one argument: an element of se¬ 
quence-pvar. 

The :count keyword argument must be a positive integer pvar with values less than 
or equal to (length!! sequence-pvar). In each processor at most count elements are 
substituted. 


Examples 
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Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a group of similar sequence operators, listed below: 
count!! count-if!! count-if-not!! 

find!! find—if!! find-if-not!! 

nsubstitute!! nsubstitute-if!! nsubstitute-if-not!! 

position!! position-if!! position-if-not!! 

substitute!! substitute-if!! substitute-if-not!! 

See also the generalized array mapping functions amap!! and *map. 
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*SUm [* Defun] 

Returns the numeric sum of the values of a pvar. 

Syntax- 

*sum numetic-pvar 

Arguments- 

numeric-pvar Numeric pvar. Pvar for which numeric sum is determined. 

Returned Value- 

sum-of-values Scalar value. Numeric sum of the values of numeric-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This returns a Lisp value that is the sum of the value of numeric-pvar in every se¬ 
lected processor. If there are no selected processors, ‘sum returns 0. 
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Examples 


Notes 


References- 

See also the related global operators: 

‘and ‘integer-length ‘logand 

‘logior ‘logxor ‘max 

*min ‘or *xor 

See also the related logical operators: 

and!! not!! or!! xor!! 
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taken-as! ! [Function] 

Returns a copy of the supplied pvar interpreted as a pvar of the specified type. 


Syntax- 

taken-as!! pvar pvar-type &optional offset 


Arguments- 

pvar Pvar expression. Pvar to be reinterpreted. 

pvar-type *Lisp type specifier. Pvar type into which pvar is reinterpreted. 

offset Integer. Offset in bits at which reinterpretation of pvar begins. 

Default is 0, indicating no offset. 


Returned Value- 

taken-as-pvar Temporary pvar of type specified by pvar-type. In each active 
processor, contains a copy of the value of pvar beginning at 
offset, considered as a value of type pvar-type. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is unlike any in Common Lisp. It is somewhat similar to the C lan¬ 
guage cast function in that it allows a pvar of one type to be used as though it were 
of another type. The function taken-as!! returns a temporary pvar containing the 
original bits of pvar interpreted as values in the data type pvar-type. No coercion or 
change in representation occurs. For example, 

(taken-as!! (!! 1.0) '(pvar (unsigned-byte 32)) 

=> (!! 1065353216) 
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Examples- 

A sample call to taken-as!! is 

(taken-as!! (!! #C(1.0 1.0)) '(pvar (array single-float (2)))) 

This demonstrates that a complex pvar can be taken as a one-dimensional array 
pvar containing 2 single-float numbers in each processor. 

(♦proclaim '(type (pvar (unsigned-byte 8)) unsigned8)) 

(♦defvar unsigned8) 

(fun-that-requires-unsigned-byte-8 unsigned8) 

(fun-that-requires-bit-vector-8 

(taken-as!! unsigned8 '(pvar (bit-vector 8)))) 
(fun-that-requires-unsigned-byte-8 unsigned8) 

Here, unsigned8is an unsigned-byte pvar of length 8. The call to taken-as!! allows 
unsigned8 to be passed to a function that expects a bit-vector pvar of length 8. 

The offset argument can be useful for selecting subportions of pvars. Consider the 
pvar unsigned16 in this example: 

(♦proclaim '(type (pvar (unsigned-byte 16)) unsignedl6)) 
(♦defvar unsignedl6) 


(need-only-8-bits 

(taken-as!! unsignedl6 '(pvar (unsigned-byte 8)) 4)) 

The pvar unsigned16 is a 16-bit pvar. The function need-only-8 requires an 8-bit 
pvar. Using taken-as!! on unsignedl6 with an offset argument of 4 causes the 4th 
through the 11th bit of unsignedl 6 in each processor to be manipulated by need- 
only-8 as an (unsigned-byte 8) pvar. 
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taken-as!! 


Notes- 

It is an error to specify a pvar-type and/or offset requiring more bits than are con¬ 
tained in the representation of pvar. It is legal, however, to specify a pvar-type that 
requires only a subset of the bits of pvar. 

This function relies on the internal representation of pvars in the Connection Ma¬ 
chine system and therefore cannot work in the ‘“Lisp simulator. 


References- 

See also the related *Lisp declaration operators: 

’locally ’proclaim unproclaim 

See also the related type coercion function coerce!!. 
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tan !! [Function] 

Takes the tangent of the supplied pvar. 

Syntax- 

tan!! radians-pvar 

Arguments- 

radians-pvar Numeric pvar. Angle, in radians, for which the tangent is calcu¬ 
lated. 

Returned Value- 

tan-pvar Temporary numeric pvar. In each active processor, contains 

the tangent of the corresponding value of radians-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

The function tan!! takes the tangent of its argument in each processor. 
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Examples - 

Notes -- 

References 
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tanh!! [Function] 

Takes the hyperbolic tangent of the supplied pvar. 


Syntax- 

tanh !! radians-pvar 


Arguments- 

radians-pvar Numeric pvar. Angle, in radians, for which the hyperbolic tan¬ 
gent is calculated. 


Returned Value- 

tanh-pvar Temporary numeric pvar. In each active processor, contains 

the hyperbolic tangent of the corresponding value of radians- 
pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a temporary pvar whose value in each processor is the hyper¬ 
bolic tangent of the value in numeric-pvar. 
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Notes- 

References 
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*trace [Macro] 

Enables tracing for the specified user-defined *Lisp functions. 


Syntax- 

* trace &rest * defun-function-names 


Arguments- 

* defun-function-names 

Symbols. Names of user-defined *Lisp functions to be traced. 


Returned Value- 

traced-functions List of symbols. Names of functions traced. 


Side Effects- 

Enables tracing on the named functions. Has no effect on functions that are 
already traced. 


Description- 

Enables tracing for the named parallel functions, which must have been defined 
using * defun. 
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Examples-- 

Invoked at top level, (‘trace foo) causes a message to be printed whenever the 
function foo is either called or exited. For example, 

(*defun self-random!! () 

(random!! (1+!! (self-address!!)))) 

(*trace self-random!!) => (*DEFUN-SELF-RANDOM!!) 

(self-random!!) => 

1 Enter *DEFUN-SELF-RANDOM!! 

1 Exit *DEFUN-SELF-RANDOM!! #<Structure PVAR A032B6> 
#<Structure PVAR A03276> 

A call (*untrace self-random!!) turns off this tracing mechanism. 

(*untrace self-random!!) => (*DEFUN-SELF-RANDOM!!) 


Notes 


References- 

The macros ‘trace and ‘untrace are the parallel equivalents of the Common Lisp 
trace and untrace functions, defined in Common Lisp: The Language. 

See also the following related operations: 

‘apply ‘defun ‘funcall 

un*defun 
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truncate!! [Function] 

Performs a parallel truncation on the supplied pvar(s). 


Syntax- 

truncate!! numeric-pvar &optional divisor-numeric-pvar 


Arguments- 

numeric-pvar Non-complex numeric pvar. Pvar to be truncated. 
divisor-numeric-pvar 

Non-complex numeric pvar. If supplied, numeric-pvar is di¬ 
vided by divisor-numeric-pvar before truncation is done. 


Returned Value- 

truncate-pvar Temporary integer pvar. In each active processor, contains the 
truncated value of numeric-pvar, divided by divisor-numeric- 
pvar if supplied. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This is the parallel equivalent of the Common Lisp function truncate, except that 
only one value (the truncated quotient) is computed and returned. 
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Examples 


Notes 


References- 

See also these related rounding operations: 
ceiling!! floor!! round!! 

See also these related floating-point rounding operations: 

fceiiing!! ffloor!! fround!! ftruncate!! 
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typed-vector!! [Function] 

Creates and returns a vector pvar of the specified type. 


Syntax- 

typed-vector!! component-type &rest component-pvars 


Arguments- 

component-type *Lisp type specifier. Type of vector pvar to create. 

component-pvars Pvars containing values of type specified by component-type. 
Determine initial contents of returned vector. 


Returned Value- 

typed-vector-pvar Temporary vector pvar, of type specified by component-type. In 
each active processor, contains a vector whose elements are the 
corresponding values of the component-pvar arguments. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function typed-vector!! creates and returns a one-dimensional array pvar of 
type component-type. The contents of the returned typed-vector-pvar are copied 
from the supplied component-pvars. In each processor, the nth element of the vec¬ 
tor in typed-vector-pvar is a copy of the value of the nth component-pvar argument. 
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Examples-- 

A call to typed-vector!! is equivalent to a *let form that declares and then initial¬ 
izes a one-dimensional array pvar. 

(typed-vector!! '(pvar single-float) 

(!! 1.0) (!! 2.0) (!! 3.0)) 

<=> 


(*let (temp) 

(declare (type (pvar (array single-float (3))) temp)) 
(dotimes (j 3) 

(*setf (aref!! temp (!! j)) (!! (float (1+ j)))))) 


Notes 


References- 

See also the pvar allocation and deallocation operations 


allocate!! 

array!! 


*deallocate 

*deallocate-*defvars 

*defvar 

front-end!! 

Net 

Net* 

make-array!! 

vector!! 

!! 
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typep!! [Function] 

Tests the values of a pvar in parallel for a specified scalar data type. 


Syntax- 

typep!! pvar scalar-type 


Arguments- 

pvar Pvar expression. Pvar for which values are tested. 

scalar-type Type specifier. Data type for which values of pvar are tested. 

Returned Value- 

typep-pvar Temporary boolean pvar. Contains the value t in each active 

processor for which the value of pvar is of the data type speci¬ 
fied by scalar-type. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function is the parallel version of the Common Lisp function typep. It tests 
whether the value of pvar in each processor is of type scalar-type. The returned 
typep-pvar pvar contains t in each processor where pvar is of type scalar-type and 
contains nil elsewhere. 


The argument pvar may be any pvar. The argument scalar-type must be one of the 
following type specifiers. 


array 

boolean 

double-float 

integer 


bignum 

character 

fixnum 

long-float 


bit 

complex 

float 

mod 


bit-vector 

complex 

front-end 

nil 
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null 

single-float 

t 


number 

standard-char 

unsigned-byte 


short-float 

string 

vector 


signed-byte 

string-char 


In addition, a user-defined structure type specifier may be used as the value of 
scalar-type 


Any of these valid type specifiers may be composed using or, and, not, and mem¬ 
ber in order to test pvar against more than one type. 


Examples 


(typep!! (!! t) 'boolean) => t!! 

These two invocations of typep!! both return t in processors 0 through 10 and nil 
elsewhere. 

(typep!! (self-address!!) '(integer 0 10)) 

(typep!! (float!! (self-address!!)) '(float 0.0 10.0)) 


Notes- 

No *Lisp equivalent of the Common Lisp satisfies type constructor is provided. 


References 


See also these related pvar data type predicates: 


booleanp!! 

floatp!! 

numberp!! 


characterp!! 

front-end-p!! 

string-char-p!! 


complexp!! 

integerp!! 

structurep!! 
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* U n d ef setf [Function] 

Removes any update function bound to the specified parallel structure access function 

by *defsetf. 


Syntax- 

* undefsetf accessor-function 


Arguments- 

accessor-function Symbol. The name of an accessor function to a parallel struc¬ 
ture, as created by *defstruct. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Removes any update function bound to accessor-function by *defsetf. 


Description- 

This function removes from the supplied accessor-function any update-function 
bindings created by *defsetf. 
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Examples- 

Notes- 

References- 

See also these related operations: 

"defsetf *setf 
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un*defun [Function] 

Undefines functions defined using *defun. 


Syntax- 

un* defun &rest * defun-names 


Arguments- 

*defun-names Symbols. Names of functions defined with *defun to undefine. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Removes all macros and functions bound to the supplied symbol names by *defun. 


Description- 

Removes the macro binding from each specified * defun name and removes the 
function binding from all symbols derived from the *defun names. 

The &rest arguments must be the symbolic names of functions that have previously 
been defined with * defun. Any number of names may be provided. 

When (*defun foo ...) is called, both a macro named foo and a function with a 
name derived from foo are created. A call to (un*defun foo) undefines both the 
macro and the associated function. 
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Examples 


Notes 


References- 

See also the following related operations: 


•apply 

•defun 

*funcall 

•trace 

•untrace 
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* Unless [ Function ] 

Evaluates *Lisp forms with the currently selected set bound according to the logical 
value of a pvar expression. 


Syntax- 

‘unless test-pvar &body body 


Arguments- 

test-pvar Pvar expression. Selects processors in which to evaluate body. 

body *Lisp forms. Evaluated with the currently selected set re¬ 

stricted to those processors in which the value of test-pvar is nil. 


Returned Value- 

body-value Scalar or pvar value. Value of final form in body. 


Side Effects- 

Temporarily restricts the currently selected set during the evaluation of the forms 
in body. 


Description- 

The ‘unless macro evaluates the supplied body forms with the currently selected 
set bound so that only processors in which test-pvar is nil are selected. The ‘unless 
macro subselects from the currently selected set of processors, so that any proces¬ 
sor that is unselected when ‘unless is called remains unselected during the evalua¬ 
tion of the body forms. All forms in the body are evaluated, even if no processors are 
selected. The value of the final expression in the body is returned whether it is a 
Lisp value or a pvar. 
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Examples-—- 

The * unless form is similar to a call to the ‘when form with the test-pvar is ne¬ 
gated. Thus: 

(♦unless unworthy-pvar . . .) 

<=> 

(♦when (not!! unworthy-pvar) . . .) 

This example increments the value of price-of-movie-pvar in all processors where 
age-pvar is greater than or equal to 12. 

(♦unless (<!! age-pvar (!! 12)) 

(*incf price-of-movie-pvar (!! 3)) 


Notes- 

Usage Note: 

Forms such as throw, return, return-from, and go may be used to exit an exter¬ 
nal block or looping construct from within a processor selection operator. 
However, doing so will leave the currently selected set in the state it was in at 
the time the non-local exit form is executed. To avoid this, use the *Lisp macro 
with-css-saved. For example, 

(block division 
(with-css-saved 

(♦unless (<=!! y (!! 0)) 

(if (*or (=!! (!! 0) x)) 

(return-from division nil) 

(/!! y x))))) 

Here return-from is used to exit from the division block if the value of x in any 
processor is zero. When the with-css-saved macro is entered, it saves the state 
of the currently selected set. When the code enclosed within the with-css- 
saved exits for any reason, either normally or via a call to an non-local exit oper¬ 
ator like return-from, the currently selected set is restored to its original state. 

See the dictionary entry for with-css-saved for more information. 
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unless 


References- 

See also the related operators 


all 


case 

case!! 

cond 

cond!! 

ecase 

ecase!! 

if 

if!! 

when 

with-css-saved 
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unproclaim [Function] 

Removes a global declaration previously made with 'proclaim. 

Syntax- 

unproclaim declaration 


Arguments- 

declaration *Lisp declaration form previously supplied as argument to 

'proclaim. Global declaration to be removed. 


Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Removes the global declaration specified by declaration. 

Description- 

Removes the effects of a declaration made with 'proclaim. 
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Examples- 

Notes- 

References- 

See also the related *Lisp declaration operators: 

"locally "proclaim 

See also the related type translation function taken-as!!. 

See also the related type coercion function coerce!!. 
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* untrace [Macro] 

Cancels tracing for the specified user-defined *Lisp functions. 


Syntax- 

* untrace &rest * defun-function-names 


Arguments- 

* defun-function-names 

Symbols. Names of user-defined *Lisp functions for which 
tracing is to be cancelled. 


Returned Value- 

traced-functions List of symbols. Names of functions untraced. 


Side Effects- 

Cancels tracing on the named functions. Has no effect on functions which are not 
currently traced. 


Description- 

Cancels tracing for the named parallel functions, which must have been defined 
using *defun. 


987 





untrace 


*Lisp Dictionary 


Examples- 

Invoked at top level, (*trace too) causes a message to be printed whenever the 
function foo is either called or exited. For example, 

(*defun self-random!! () 

(random!! (1+!! (self-address!!)))) 

(♦trace self-random!!) => (*DEFUN-SELF-RANDOM!!) 

(self-random!!) => 

1 Enter *DEFUN-SELF-RANDOM!! 

1 Exit *DEFUN-SELF-RANDOM!! #<Structure PVAR A032B6> 
#<Structure PVAR A03276> 

A call (* untrace self-random!!) turns off this tracing mechanism. 

(♦untrace self-random!!) => (*DEFUN-SELF-RANDOM!!) 


Notes 


References- 

The macros *trace and * untrace are the parallel equivalents of the Common Lisp 
trace and untrace functions, defined in Common Lisp: The Language. 

See also the following related operations: 

•apply *defun ‘funcall 

un*defun 
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upper-case-p!! [Function] 

Performs a parallel test for upper-case characters on the supplied pvar. 


Syntax- 

upper-case-p!! character-pvar 


Arguments- 

character-pvar Character pvar. Tested in parallel for upper-case characters. 


Returned Value- 

uppercasep-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the corresponding value of character-pvar is 
an upper-case alphabetic character. Contains nil in all other 
processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This predicate returns a pvar that has the value t in each processor where the 
supplied character-pvar contains an upper-case character, and the value nil in all 
other processors. 
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Examples - 

Notes- 

References 
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vceiling [Function] 

Takes the ceiling of the supplied front-end vector. 

Syntax- 

vceiling vector 


Arguments- 

vector Front-end vector. Vector for which ceiling is taken. 

Returned Value- 

vector-ceiling Vector. Elementwise ceiling of vector. 

Side Effects- 

None. 


Description- 

Takes the ceiling of each element of vector. 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vector!! [ Function } 

Creates and returns a vector pvar containing the values of the supplied pvars. 

Syntax- 

vector!! &rest element-pvars 

Arguments- 

element-pvars Pvars. Used to initialize the returned vector pvar. 

Returned Value- 

vector-pvar Vector pvar. In each active processor, contains a vector whose 

elements are the corresponding values of the element-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

Creates and returns a vector pvar, initialized with the values of the supplied 
element-pvars. 

The standard rules of coercion are used to determine the element type of the result¬ 
ing vector pvar. For instance, a mixture of integer and floating point elements 
yields a floating-point result. A mixture of floating-point and complex elements 
yields a complex result. An error is signaled if the data types present are not all 
compatible. (For instance, a string-char element and a floating-point element are 
not compatible.) 
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Examples- 

(pref (vector!! (self-address!!) (self-address!!)) 25) 
=> #(25 25). 


Notes 


References- 

The vector!! function is similar to the typed-vector!! function. However an ele¬ 
ment-type argument is not required for vector!!. See the definition of typed-vec¬ 
tor!! for more information. 

See also the pvar allocation and deallocation operations 


allocate!! 

array!! 


* deallocate 

*deallocate-*defvars 

*defvar 

front-end!! 

Met 

Met* 

make-array!! 

!! 



\ 
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vector-normal [Function] 

Returns the normalized cross product of two front-end vectors. 


Syntax- 

vector-normal vectorl vector2 


Arguments- 

vectorl, vector2 Front-end vectors. Vectors for which normalized cross product 

is calculated. Vectors must be at least 3 elements in length. 


Returned Value- 

normal-vector Front-end vector. Normalized cross product of vectorl and 
vector2. 


Side Effects 

None. 


Description- 

This is the serial (front end) equivalent of vector-normal!!, which is not implem¬ 
ented. The function sf-vector-normal!! provides equivalent functionality for sing¬ 
le-float pvars. 

This function is equivalent to 

(vscale-to-unit-vector 

(cross-product vector-pvarl vector-pvar2)) 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vfloor [Function] 

Takes the floor of the supplied front-end vector. 

Syntax- 

vfloor vector 


Arguments- 

vector Front-end vector. Vector for which floor is taken. 


Returned Value- 

vector-floor Vector. Elementwise floor of vector. 


Side Effects 

None. 


Description- 

Takes the floor of each element of vector. 


997 




vfloor 


*Lisp Dictionary 


Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vp-set-deallOCated-p [Function] 

Tests whether the supplied VP set has been deallocated. 

Syntax- 

vp-set-deallocated-p vp-set 


Arguments- 

vp-set VP set object. VP set to be tested for deallocation. 

Returned Value- 

deallocated-p Boolean. The value t if vp-set has been deallocated, and nil oth¬ 

erwise. 

Side Effects- 

None. 


Description- 

Determines whether the specified VP set has been deallocated by a call to deallo- 
cate-vp-set. 

This function returns t if the supplied VP set has been deallocated, and nil other¬ 
wise. 


999 







vp-set-deallocated-p 


*Lisp Dictionary 


Examples 


Notes- 

The vp-set argument must be a *Lisp VP set, created by a call to a *Lisp operator 
such as def-vp-set or create-vp-set. 


References- 

See also the following VP set information operations: 

dimension-size dimension-address-length 

describe-vp-set 

vp-set-dimensions vp-set-rank 

vp-set-total-size vp-set-vp-ratio 
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vp-set-dimensions [Function] 

Returns the dimensions of the supplied VP set as a list of integers. 

Syntax- 

vp-set-dimensions vp-set 

Arguments- 

vp-set VP set object. VP set for which dimensions are returned. 

Returned Value- 

dimension-list List of integers. Dimensions of the supplied VP set. 

Side Effects- 

None. 

Description- 

This function returns a list of integers specifying the dimensions of VP set vp-set. 
The vp-set argument must be a defined, allocated VP set. 
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Examples- 

Notes- 

The vp-set argument must be a *Lisp VP set, created by a call to a *Lisp operator 
such as def-vp-set or create-vp-set. 

References- 

See also the following VP set information operations: 

dimension-size dimension-address-length 

describe-vp-set vp-set-deallocated-p 

vp-set-rank 

vp-set-total-size vp-set-vp-ratio 
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vp-set-rank [Function] 

Returns the rank, or number of dimensions, in the supplied VP set. 

Syntax- 

vp-set-rank vp-set 

Arguments- 

vp-set VP set object. VP set for which the rank is returned. 

Returned Value- 

rank Integer. The rank, or number of dimensions, of the supplied VP 

set. 

Side Effects- 

None. 

Description- 

This function returns the number of dimensions in the specified VP set. 

The vp-set argument must be a defined, allocated VP set. 
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Examples- 

Notes- 

The vp-set argument must be a *Lisp VP set, created by a call to a ’“Lisp operator 
such as def-vp-set or create-vp-set. 

References- 

See also the following VP set information operations: 

dimension-size dimension-address-length 

describe-vp-set vp-set-deallocated-p 

vp-set-dimensions vp-set-total-size 

vp-set-vp-ratio 
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vp-set-total-size [Function] 

Returns the total number of processors in the supplied VP set. 

Syntax- 

vp-set-total-size vp-set 

Arguments- 

vp-set VP set object. VP set for which the total size is returned. 

Returned Value- 

total-size Integer. Total number of processors in vp-set. 

Side Effects- 

None. 

Description- 

This function returns the total number of processors in the specified VP set. 
The vp-set argument must be a defined, allocated VP set. 
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Examples- 

Notes- 

The vp-set argument must be a *Lisp VP set, created by a call to a *Lisp operator 
such as def-vp-set or create-vp-set. 

References- 

See also the following VP set information operations: 

dimension-size dimension-address-length 

describe-vp-set vp-set-deallocated-p 

vp-set-dimensions vp-set-rank 

vp-set-total-size 
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vp-set-vp-ratio [Function] 

This function returns the VP ratio for the supplied VP set. 

Syntax- 

vp-set-vp-ratio vp-set 


Arguments- 

vp-set VP set object. VP set for which the VP ratio is returned. 

Returned Value-- 

retumed-value Returned value. 

Side Effects- 

None. 

Description- 

This function returns the VP ratio, or the number of virtual processors each physi¬ 
cal processor is simulating, for the specified VP set. 

The vp-set argument must be a defined, allocated VP set. 
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vp-set-vp-ratio 


*Lisp Dictionary 


Examples 


Notes-- 

The vp-set argument must be a *Lisp VP set, created by a call to a *Lisp operator 
such as def-vp-set or create-vp-set. 


References- 

See also the following VP set information operations: 

dimension-size dimension-address-length 

describe-vp-set vp-set-deallocated-p 

vp-set-dimensions vp-set-rank 

vp-set-total-size 
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vround [Function] 

Rounds the supplied front-end vector. 

Syntax- 

vround vector 


Arguments- 

vector Non-complex numeric vector. Vector for which round is taken. 

Returned Value- 

vector-round Numeric value. Rounded value of vector. 

Side Effects- 

None. 


Description- 

This function rounds each element of vector to the nearest integer. 
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vround 


*Lisp Dictionary 


Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vscale 

Scales a front-end vector by a scalar value. 

Syntax- 

vscale vector scalar 

Arguments 

vector 
scalar 

Returned Value- 

scaled-vector The result of multiplying each element of vector by scalar. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent of vscale!!. 


Front-end vector. Vector to be scaled. 

Scalar value. Value by which to scale vector. 


[Function] 
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vscale 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 

operators, listed below: 

dot-product 

cross-product 


v+ 

v+-constant 


V- 

v—constant 


V* 

v*-constant 

v/-constant 

vabs 

vabs-squared 

vceiling 

vector-normal 

vfloor 

vround 

vscale 

vscale-to-unit-vector 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vscale!! 


VSCale!! [ Function] 

Calculates in parallel the result of scaling the supplied vector pvar by a scalar pvar. 


Syntax- 

vscale!! vector-pvar scalar-pvar 


Arguments- 

vector-pvar Vector pvar. Vector pvar to be scaled. 

scalar-pvar Scalar pvar. Value by which vector-pvar is scaled. 


Returned Value- 

result-pvar Temporary vector pvar. In each active processor, contains the 

result of scaling each element of the vector in vector-pvar by the 
value in scalar-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

This function returns a vector pvar of the proper type and size according to the 
*Lisp contagion and sizing rules. 

In each processor, each element of the input pvar, vector-pvar, is multiplied by the 
single element of scalar-pvar in that processor. 
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vscale!! 


Examples 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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vscale-to-unit-vector 


VSCale-tO-unit-veCtor [Function] 

Returns the result of scaling the supplied front-end vector to unit length. 

Syntax- 

vscale-to-unit-vector vector 

Arguments- 

vector Front-end vector. Vector to be scaled. 

Returned Value- 

unit-vector Front-end vector. The result of scaling vector to a unit-length 

vector. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent of vscale-to-unit-vector!!. 

This function is equivalent to 

(vscale vector (/ (vabs vector))) 

except that vector is evaluated once. 
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vscale-to-unit-vector 


Examples 


Notes- 

It is an error if every element of vector is 0, or if (vabs vector ) is 0. 


References 


This function is one of a number of front-end vector operators, listed below: 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 
v+-constant 
v—constant 
v*-constant 
vabs-squared 
vfloor 

vscale-to-unit-vector 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vscale-to-unit-vector!! 


VSCale-tO-unit-vector!! [Function] 

Calculates in parallel the result of scaling the supplied vector pvar to unit length. 

Syntax- 

vscale-to-unit-vector! ! vector-pvar 

Arguments- 

vector-pvar Vector pvar. Vector pvar to be scaled. 

Returned Value- 

result-pvar Temporary vector pvar. In each active processor, contains the 

result of scaling the value of vector-pvar to a unit-length vector. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function is equivalent to 

(vscale!! vector-pvar (/!! (vabs!! vector-pvar))) 
except that vector-pvar is evaluated once. 
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vscale-to-unit-vector!! 


*IJsp Dictionary 


Examples- 

It is an error if vector-pvar contains a zero-length vector in any active processor. 

Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*v$et-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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*vset-components [*Defun] 

Copies the supplied element pvars into the supplied vector pvar in parallel. 


Syntax- 

*vset-components vector-pvar &rest element-pvars 


Arguments- 

vector-pvar Vector pvar. Vector pvar into which elements are stored. 

element-pvars Pvar(s) of same type as elements of vector-pvar. Element(s) to 
be stored. Either a single pvar or as many pvars as there are 
elements in vector-pvar. 

Returned Value- 

nil Evaluated for side effect only. 


Side Effects- 

Destructively alters the value of vector-pvar in each active processor to contain the 
elements specified by the supplied element-pvars. 


Description- 

This function copies the values of the supplied element-pvars into the supplied 
vector-pvar in parallel. 

If there is a single element-pvar argument, then every element of vector-pvar is ‘set 
to it. If there are as many element-pvar arguments as there are elements in vector- 
pvar, then the jth element of vector-pvar is ‘set to the jth element-pvar argument. 
An error will be signaled if the number of element-pvar arguments is not either 1 or 
the number of elements in the vector-pvar. 


1019 




vset-components 


*Lisp Dictionary 


Examples 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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Vtruncate [Function] 

Truncates the supplied front-end vector. 

Syntax- 

vtruncate vector 

Arguments- 

vector Front-end vector. Vector to be truncated. 

Returned Value- 

vector-truncate Numeric value. Truncated value of vector. 

Side Effects- 

None. 

Description- 

Truncates each element of vector. 
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vtruncate 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 

operators, listed below: 

dot-product 

cross-product 


v+ 

v+-constant 


V- 

v—constant 


V* 

v*-constant 

v/-constant 

vabs 

vabs-squared 

vceiling 

vector-normal 

vfloor 

vround 

vscale 

vscale-to-unit-vector 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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v+ 


V + [Function] 

Returns the vector sum of the supplied front-end vectors. 

Syntax- 

v+ vector &rest vectors 

Arguments- 

vector, vectors Front-end vectors. Vectors for which vector sum is calculated. 

All vectors supplied must have the same element size. 

Returned Value- 

result-vector Front-end vector. The vector sum of the supplied vector argu¬ 
ments. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent of v+M. 
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v+ 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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v+!! 


V + !! [Function] 

Calculates in parallel the vector sum of the supplied vector pvars. 


Syntax- 

v+M vector-pvar &rest vector-pvars 


Arguments- 

vector-pvar, vector-pvars 

Vector pvars. Pvars for which vector sum is calculated. All 
pvars supplied must have the same element size. 


Returned Value- 

result-vector-pvar Temporary vector pvar. In each active processor, contains the 
sum of vector-pvar with the corresponding values of the vector- 
pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The v+!! function calculates in each processor the element-wise vector sum of the 
values of the supplied vector-pvars. If a single argument is supplied, its values are 
simply copied into the result-pvar. 
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v+n 


*Lisp Dictionary 


Examples- 

The following equivalence holds: 

(v+M vector-pvar-1 vector-pvar-2 ... vector-pvar-n) 

<=> 

(amap!! ' + ! vector-pvar-1 vector-pvar-2 ... vector-pvar-n) 


Notes 


References 


This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

v+M 

vabs!! 

vscale-to-unit-vector!! 


dot-product!! 

v-!! 

vabs-squared!! 

*vset-components 


v*M 

vscale!! 


sf-cross-product!! 

sf-v*-constant!! 

sf-vabs-squared!! 


sf-v+-constant!! sf-v—constant!! 

sf-v/-constant!! sf-vabs!! 

sf-vector-normal!! sf-vscale-to-unit-vector!! 


dsf-cross-product!! dsf-vector-normal!! 

dsf-vscale-to-unit-vector!! 
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V + -constant [Function] 

Adds a scalar value to each element of a vector. 

Syntax- 

v+-constant vector scalar 

Arguments 

vector 
scalar 

Returned Value- 

result-vector Front-end vector. The result of adding scalar to each element of 

vector. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent of v+-constant! !, which is not implemented. 
The function sf-v+-constant!! provides equivalent functionality for single-float 
pvars. 


Front-end vector. Vector to which scalar is added. 
Scalar value. Added to each vector element of vector. 
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v+-con$tant 


*Lisp Dictionary 


Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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v- 


V- [Function] 

Returns the vector difference of the supplied front-end vectors. 


Syntax- 

v- vector &rest vectors 


Arguments- 

vector, vectors Front-end vectors. Vectors for which vector difference is calcu¬ 
lated. All vectors supplied must have the same element size. 


Returned Value- 

result-vector Front-end vector. The result of subtracting each of the vectors 
from the supplied vector argument. If only one vector argument 
is supplied, its elementwise negation is returned. 

Side Effects- 

None. 


Description- 

This is the serial (front end) equivalent of v-!!. 
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Examples 

Notes- 


References- 

This function is one of a number of front-end vector operators, listed below: 

dot-product cross-product 

v+ v+-constant 

v- v—constant 

v* v*-constant v/-constant 

vabs vabs-squared vceiling 

vector-normal vfloor vround 

vscale vscale-to-unit-vector vtruncate 

These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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v-!! 


V-!! [Function] 

Calculates in parallel the vector difference or negation of the supplied vector pvars. 


Syntax- 

v-M vector-pvar &rest vector-pvars 


Arguments- 

vector-pvar Vector pvar. Pvar from which the supplied vector-pvars are 

subtracted. All pvars supplied must have the same element 
size. Negated if no other vector-pvars are supplied. 

vector-pvars Vector pvars. Subtracted in order from vector-pvar. 

Returned Value- 

result-vector-pvar Temporary vector pvar. In each active processor, contains the 
result of subtracting the value of each of the vector-pvars from 
the value of vector-pvar. If only one vector-pvar is supplied, its 
negation is returned. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The v— !! function calculates in each processor the element-wise vector difference 
of the values of the supplied vector-pvars. If a single vector-pvar argument is 
supplied, its elementwise negation is returned. 
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Examples- 

The following equivalence holds: 

(v-!! vector-pvar-1 vector-pvar-2 ... vector-pvar-n) 

<=> 

(amap!! '-!! vector-pvar-1 vector-pvar-2 ... vector-pvar-n) 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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V— constant [Function] 

Subtracts a scalar value from each element of a vector. 

Syntax- 

v—constant vector scalar 

Arguments 

vector 
scalar 

Returned Value- 

result-vector Front-end vector. The result of subtracting scalar from each 
element of vector. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent of v—constant! !, which is not implemented. 
The function sf-v—constant!! provides equivalent functionality for single-float 
pvars. 


Front-end vector. Vector from which scalar is subtracted. 
Scalar value. Subtracted from each vector element of vector. 
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v—constant 


*Lisp Dictionary 


Examples 


Notes 


References 


This function is one of a number of front-end vector operators, listed below: 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 
v+-constant 
v—constant 
v* -constant 
vabs-squared 
vfloor 

vscale-to-unit-vector 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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v* 


V* [Function] 

Returns the element-wise product of the supplied front-end vectors. 


Syntax- 

v* vector &rest vectors 


Arguments- 

vector, vectors Front-end vectors. Vectors for which element-wise product is 
calculated. All vectors supplied must have the same element 
size. 


Returned Value- 

result-vector Front-end vector. The element-wise product of the supplied 
vector arguments. 


Side Effects 

None. 


Description- 

This is the serial (front end) equivalent of v*!!. 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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v*!! 


V*!! [Function] 

Calculates in parallel the element-wise product of the supplied vector pvars. 


Syntax-- 

v*M vector-pvar &rest vector-pvars 


Arguments- 

vector-pvar, vector-pvars 

Vector pvars, for which the element-wise product is calculated. 
All pvars supplied must have the same element size. 


Returned Value- 

result-vector-pvar Temporary vector pvar. In each active processor, contains the 
the element-wise product of vector-pvar with the correspond¬ 
ing values of the vector-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The v*!! function calculates in each processor the element-wise vector product of 
the values of the supplied vector-pvars. If a single argument is supplied, its values 
are simply copied into the result-pvar. 
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Examples -- 

The following equivalence holds: 

(v*!! vector-pvar-1 vector-pvar-2 ... vector-pvar-n) 

<=> 

(amap!! '*!! vector-pvar-1 vector-pvar-2 ... vector-pvar-n) 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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v*-constant 


V*-COnstant [ Function] 

Multiplies each element of a vector by a scalar value. 


Syntax- 

v*-constant vector scalar 


Arguments- 

vector Front-end vector. Vector to be multipled by scalar. 

scalar Scalar value. Value by which each element of vector is multi¬ 

plied. 


Returned Value- 

result-vector Front-end vector. The result of multiplying each element of 
vector by scalar. 


Side Effects 

None. 


Description- 

This is the serial (front end) equivalent of v*-constant! !, which is not implemented. 
The function sf-v*-constant!! provides equivalent functionality for single-float 
pvars. 
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v*-constant 
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Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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v/-constant 


v/-COnstant [Function] 

Divides each element of a vector by a scalar value. 

Syntax- 

v/-constant vector scalar 


Arguments- 

vector Front-end vector. Vector to be divided by scalar. 

scalar Scalar value. Value by which each element of vector is divided. 


Returned Value- 

result-vector Front-end vector. The result of dividing each element of vector 
by scalar. 


Side Effects 

None. 


Description- 

This is the serial (front end) equivalent of v/-constant!!, which is not implemented. 
The function sf-v/-constant!! provides equivalent functionality for single-float 
pvars. 
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v/-constant 


*Lisp Dictionary 


Examples 


Notes 


References 


This function is one of a number of front-end vector operators, listed below: 


dot-product 

v+ 

V- 

V* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vabs 


vabs [Function] 

Returns the vector magnitude of the supplied front-end vector. 

Syntax- 

vabs vector 


Arguments- 

vector Front-end vector. Vector for which magnitude is returned. 

Returned Value- 

vector-length Numeric value. Magnitude of vector. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent of vabs!!. 

This function is equivalent to 

(sqrt (vabs-squared vector)) 
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vabs 


*Lisp Dictionary 


Examples 


Notes 


References 


This function is one of a number of front-end vector 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


operators, listed below: 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vabs!! 


vabs!! [Function] 

Calculates in parallel the vector magnitude of the supplied vector pvar. 

Syntax- 

vabs!! vector-pvar 


Arguments- 

vector-pvar Vector pvar. Pvar for which vector magnitude is computed. 

Returned Value- 

result-pvar Temporary vector pvar. In each active processor, contains the 

vector magnitude of the corresponding value of vector-pvar. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This function is equivalent to 

(sqrt!! (vabs-squared!! vector-pvar)) 

This function returns a scalar pvar of type float if the element type of vector-pvar is 
non-complex. If the element type of vector-pvar is complex, vabs!! returns a com¬ 
plex pvar. 
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Examples- 

Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 

References- 

This function is one of a number of vector pvar operators, listed below: 

cross-product!! dot-product!! 

v+U v-!! v*!! 

vabs!! vabs-squared!! vscale!! 

vscale-to-unit-vector!! * vset-components 

sf-cross-product!! sf-v+-constant!! sf-v—constant!! 

sf-v*-constant!! sf-v/-constant!! sf-vabs!! 

sf-vabs-squared!! sf-vector-normal!! sf-vscale-to-unit-vector!! 

dsf-cross-product!! dsf-vector-normal!! 

dsf-vscale-to-unit-vector!! 
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vabs-squared 


vabs-squared [Function] 

Returns the squared magnitude of the supplied front-end vector. 

Syntax- 

vabs-squared vector 


Arguments- 

vector Front-end vector. Vector for which squared magnitude is 

returned. 

Returned Value- 

vector-square Numeric value. Squared magnitude of vector. 

Side Effects- 

None. 

Description- 

This is the serial (front end) equivalent vabs-squared!!. 

This function is equivalent to 

(dot-product vector vector) 
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Examples 


Notes- 

Compiler Note: 

The *Lisp compiler does not compile this operation. 


References 


This function is one of a number of front-end vector operators, listed below: 


dot-product 

v+ 

v- 

v* 

vabs 

vector-normal 

vscale 


cross-product 

v+-constant 

v—constant 

v*-constant 

vabs-squared 

vfloor 

vscale-to-unit-vector 


v/-constant 

vceiling 

vround 

vtruncate 


These functions are the serial equivalents of the corresponding vector pvar 
operations. See Chapter 1, “*Lisp Overview” of this Dictionary for a list of these 
functions. 
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vabs-squared!! [Function] 

Calculates in parallel the squared magnitude of the supplied vector pvar. 


Syntax- 

vabs-squared!! vector-pvar 


Arguments- 

vector-pvar Vector pvar. Pvar for which squared magnitude is computed. 


Returned Value- 

result-pvar Temporary vector pvar. In each active processor, contains the 

squared magnitude of the corresponding value of vector-pvar. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The vabs-squared!! function calculates in parallel the squared magnitude of the 
supplied vector-pvar. The result-pvar is of the same type as the supplied vector- 
pvar, but may be of larger size if vector-pvar is an unsigned or signed integer pvar. 

Calling (vabs-squared!! vector-pvar) is equivalent to 
(dot-product!! vector-pvar vector-pvar) 
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vabs-squared!! 


Examples 


Notes 


References- 

This function is one of a number of vector pvar operators, listed below: 


cross-product!! 

dot-product!! 


v+!! 

v-!! 

v*!! 

vabs!! 

vabs-squared!! 

vscale!! 

vscale-to-unit-vector!! 

*vset-components 


sf-cross-product!! 

sf-v+-constant!! 

sf-v—constant!! 

sf-v*-constant!! 

sf-v/-constant!! 

sf-vabs!! 

sf-vabs-squared!! 

sf-vector-normal!! 

sf-vscale-to-unit-vector!! 

dsf-cross-product!! 

dsf-vector-normal!! 



dsf-vscale-to-unit-vector!! 
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*warm-boOt [Macro] 

Clears the *Lisp stack, deallocating local and temporary pvars, resets the currently 
selected set of all VP sets, and resets certain internal states of the CM. 


Syntax- 

*warm-boot 


Arguments- 

Takes no arguments. 

Returned Value- 

nil Evaluated for side effects only. 

Side Effects- 

Clears the *Lisp stack, deallocating local and temporary pvars, resets the currently 
selected set of all VP sets, and resets certain internal states of the CM. 


Description- 

The 'warm-boot macro resets *Lisp and the CM. It must be called whenever the 
CM has been placed in an inconsistent state, such as by a program error or by 
manually aborting a running function. 

The 'warm-boot macro clears the *Lisp stack and restores both *Lisp and the CM 
to a consistent, usable state. The *Lisp heap is not cleared, so pvars allocated on 
the heap (permanent and global) remain allocated. 
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Specifically, executing *warm-boot has the following effects: 

■ All virtual processors in all VP sets are made active; no processors remain 
unselected. 

■ The *default-vp-set* is selected as the *current-vp-set* 

■ The Connection Machine stack is cleared and all pvars allocated on the 
stack (i.e., any not created by allocate!! or *defvar) are deallocated. 


Examples- 

A top-level call to *warm-boot resets the CM. 

(*warm-boot) 

The following example demonstrates why it is necessary to call *warm-boot after 
aborting execution in the middle of a *Lisp program. 

(*cold-boot :initial-dimensions ' (512)) 

(*let (x) 

(declare (type single-float-pvar x)) 

(*when (evenp!! (self-address!!)) (*set x (!! #\x)))) 

Error: In interpreted *SET. 

The source expression in a float-general *set contains some¬ 
thing that is not a float. 

A pvar of type STRING-CHAR caused the error. 

-> (*sum (!! 1)) 

256 

The error occurs while the currently selected set has been restricted to the even 
processors. The following example shows that the currently selected set is not 
automatically restored by aborting back to top level. 

-> Abort 

Return to Lisp Top Level in Dynamic Lisp Listener 1 
Back to Lisp Top Level in Dynamic Lisp Listener 1. 

(*sum (!! 1)) => 256 
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A call to ‘warm-boot resets the currently selected set so that all processors are 
active. 

(*warm-boot) 

(*sum (!! 1)) => 512 

Interrupting or aborting a program may leave the front-end/CM connection in an 
inconsistent state, preventing the front end from issuing instructions to the CM. A 
call to ‘warm-boot resets the connection, allowing the front end to communicate 
with the CM. 


Notes- 

The ‘warm-boot macro is intended to be called at top level. It should not in general 
be called from within user code, because it forcibly deallocates any existing local 
and temporary pvars. 

One exception to this rule is that ‘warm-boot may be called as the first body form 
of a function intended to be called at top level, as in 

(defun top-level () 

(*warm-boot) 

(initialize-pvars) 

(main-function) 

(clean-up-and-print-results) 

) 

Here, ‘warm-boot is used to ensure that the Connection Machine is reset and 
ready for use before the initialization function and main functions of the user’s 
program are called. 


References- 

See also the related Connection Machine initialization operator ‘cold-boot. 

See also the initialization-list functions add-initialization and delete-initialization. 
See also the character attribute initialization operator initialize-character. 
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*when [Macro] 

Evaluates *Lisp forms with the currently selected set bound according to the logical 
value of a pvar expression. 


Syntax- 

*when test-pvar &body body 


Arguments- 

test-pvar Pvar expression. Selects processors in which to evaluate body. 

body *Lisp forms. Evaluated with the currently selected set re¬ 

stricted to those processors in which the value of test-pvar is t. 


Returned Value- 

body-value Scalar or pvar value. Value of final form in body. 

Side Effects- 

Temporarily restricts the currently selected set during the evaluation of the forms 
in body. 


Description- 

The *when macro evaluates the supplied body forms with the currently selected set 
bound so that only processors in which test-pvar is non-nil are selected. The *when 
macro subselects from the currently selected set of processors, so that any proces¬ 
sor that is unselected when *when is called remains unselected during the evalua¬ 
tion of the body forms. All forms in the body are evaluated, even if no processors are 
selected. The value of the final expression in the body is returned, whether it is a 
Lisp value or a pvar. 
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Examples- 

This example increments the value of price-of-movie-pvar in all processors where 
age-pvar is greater than or equal to 12. 

(♦when (>=!! age-pvar (!! 12)) 

(*incf price-of-movie-pvar (!! 3)) 

This example shows how * when may be nested to select processors in which a data 
pvar meets multiple criteria. The vaue of intensity-pvar is copied into real-edge- 
pvar only in those processors where part-of-edge-p is non-nil, and where 
intensity-pvar is greater than 9.0. 

(♦when part-of-edge-p 

(♦when (>!! intensity-pvar (!! 9.0)) 

(♦set real-edge-pvar intensity-pvar))) 


Notes- 

Usage Note: 

Forms such as throw, return, return-f rom, and go may be used to exit an exter¬ 
nal block or looping construct from within a processor selection operator. 
However, doing so will leave the currently selected set in the state it was in at 
the time the non-local exit form is executed. To avoid this, use the *Lisp macro 
with-css-saved. For example, 

(block division 
(with-css-saved 

(♦when (>!! y (!! 0)) 

(if (*or (=!! (!! 0) x)) 

(return-from division nil) 

(/!! y x))))) 

Here return-from is used to exit from the division block if the value of x in any 
processor is zero. When the with-css-saved macro is entered, it saves the state 
of the currently selected set. When the code enclosed within the with-css- 
saved exits for any reason, either normally or via a call to an non-local exit oper¬ 
ator like return-from, the currently selected set is restored to its original state. 

See the dictionary entry for with-css-saved for more information. 
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References- 

See also the related operators 

*all 

'case case!! 

*cond cond!! 

*ecase ecase!! 

'if if!! 

'unless with-css-saved 
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With-CSS-Saved [Macro] 

Records the state of the currently selected set and ensures that it is automatically 
restored when evaluation of the supplied body forms terminates. 


Syntax- 

with-css-saved &body body 


Arguments- 

body *Lisp forms. Body forms to be evaluated. 


Returned Value- 

body-value Scalar or pvar value. Value returned by final form in body. 


Side Effects- 

Records the state of the currently selected set before evaluating the forms in body 
and ensures that the currently selected set is restored when evaluation of the body 
forms terminates. 


Description- 

The with-css-saved macro records the state of the currently selected set and en¬ 
sures that when evaluation of the supplied body forms terminates for any reason, 
the recorded currently selected set of active processors is automatically restored to 
its original state. 

This form should be used wherever evaluation of the forms in body might cause 
control flow to abnormally pass out of a *Lisp form that restricts the currently se¬ 
lected set (for example, by a call to throw, return, return-from, or go within a 
•when form). The with-css-saved macro uses an unwind-protect to trap such 
non-local exits and restore the currently selected set. 
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Examples- 

The following function definitions demonstrate the use of with-css-saved. Both 
functions return the result of dividing y by x in all processors where y > 0. If any 
value of x is zero, both functions return nil. 

(defun css-not-preserved (x y) 

(block exit 

(*when (>!! y (!! 0)) 

(if (*or (zerop!! x)) 

(return-from exit nil) 

(/!! y x) 

)))) 


(defun css-preserved (x y) 

(block exit 

(with-css-saved 

(*when (>!! y (!! 0)) 

(if (*or (zerop!! x)) 

(return-from exit nil) 

(/!! y x) 

))))) 

The difference between the functions lies in the way css-preserved uses the 
with-css-saved macro around its conditional to restore the currently selected set. 
For example, given the configuration defined by 

(♦cold-boot :initial-dimensions '(512)) 
the expression 

(*all (progn (css-not-preserved (!! 0) (self-address!!)) 

(♦sum (!! 1)))) 


returns 511. 

The pvar returned by (self-address!!) isOin processor zero, so css-not-preserved 
deselects processor 0. When the call to return-from in css-not-preserved is 
executed because x contains the value 0 in every processor, css-not-preserved 
does nothing to restore the currently selected set, leaving processor 0 deselected. 
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The expression 

(*all (progn (css-preserved (!! 0) (self-address!!)) 

(*sum (!! 1)))) 

returns 512. By enclosing the *when conditional with the with-css-saved macro, 
the css-preserved function insures that the currently selected set is automatically 
restored when the call to return-from is executed. 


Notes- 

For the purposes of forms that execute non-local exits, the with-css-saved macro 
is functionally equivalent to a call to unwind-protect. When a non-local exit is 
performed, an unwind-protect is executed to restore the currently selected set, and 
then the exit continues normally. Evaluation does not continue with the form 
immediately following the with-css-saved. For example, when 

(catch 'exit 

(with-css-saved 
(yin data-pvar) 

(when win-yin 

(throw 'exit nil))) 

(yang data-pvar)) 

is evaluated, if the variable win-yin has the value t, then (yin data-pvar) is 
evaluated, but (yang data-pvar) is not. 


References- 

See also the processor selection operators 


all 


case 

case!! 

cond 

cond!! 

ecase 

ecase!! 

if 

if!! 

unless 

*when 
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with-processors-allocated-for-vp-set 


with-processors-allocated-for-vp-set [Macro] 

Temporarily instantiates (assigns a geometry to) a flexible VP set for the duration of a 
set of body forms. 


Syntax- 

with-processors-allocated-for-vp-set ( vp-set &key :dimensions :geometry) 

&body body 


Arguments — 

vp-set 

:dimensions 

: geometry 

body 


Flexible VP set. Virtual processor set defined with def-vp-set. 

Integer list or nil. Size of dimensions with which to instantiate 
vp-set. Must be nil if geometry argument is supplied. 

Geometry object, obtained by calling the function create-ge- 
ometry. Defines geometry of vp-set. 

*Lisp forms. Body forms to be evaluated with vp-set 
instantiated. 


Returned Value- 

body-value Scalar or pvar value. Value of final form in body. 


Side Effects- 

Temporarily defines geometry of vp-set and allocates any associated pvars, for the 
duration of the body forms, then deinstantiates vp-set and deallocates any asso¬ 
ciated pvars. 
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Description- 

This macro expands into a form that instantiates vp-set by a call to allocate-pro- 
cessors-f or-vp-set, using the supplied dimensions or geometry as arguments. As 
with the allocate-processors-f or-vp-set function, one or the other of the : dimen¬ 
sions or : geometry arguments may be supplied, but not both. The form then exe¬ 
cutes the supplied body forms and finally calls deallocate-processors-for-vp-set 
to deinstantiate vp-set . 


Examples- 

A sample call to with-processors-allocated-for-vp-set is 

(def-vp-set my-vp-set nil 

:*defvars '((value-pvar (self-address!!)))) 

(with-processors-allocated-for-vp-set (my-vp-set 

:dimensions '(32 32 32)) 

(*with-vp-set my-vp-set 

(*set value-pvar (*!! value-pvar (!! 2))) 

(ppp value-pvar :end 8))) 

0 2 4 6 8 10 12 14 

The following example shows how a flexible VP set can be used repeatedly to pro¬ 
cess a set of data files. In the example, a single flexible VP set is used, which is 
instantiated and deinstatiated once for each file in such a way that it is just large 
enough to hold each file’s data. 

(def-vp-set file-data-vp-set nil 

:*defvars '((file-data-pvar))) 

(dolist (file files-to-be-processed) 

(let ((file-size (get-file-size file))) 

(with-processors-allocated-for-vp-set file-data-vp-set 
:dimensions (next-power-of-two->= file-size) 
(*with-vp-set file-data-vp-set 

(*set file-data-pvar (read-file-data!!)) 
(process-file-data file-data-pvar))))) 
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Notes 


References- 

See also the following flexible VP set operators: 

allocate-vp-set-processors allocate-processors-for-vp-set 

deallocate-vp-set-processors deallocate-processors-for-vp-set 

aet-vp-set-geometry 
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*With-vp-Set [Macro] 

Temporarily binds the supplied VP set as the current VP set for the duration of the 
supplied body forms. 


Syntax- 

*with-vp-set vp-set & body body 


Arguments- 

vp-set VP set object. VP set to be made current. Must be defined and 

instantiated. 

body *Lisp forms. Body forms to be evaluated. 


Returned Value- 

body-value Scalar or pvar value. Value of final form in body. 

Side Effects- 

Temporarily changes the current VP set to vp-set during the evaluation of the 
supplied body forms. 


Description- 

This macro is used to temporarily switch VP sets for the duration of a section of 
code. 

The currently selected VP set is dynamically scoped. The *with-vp-set form tem¬ 
porarily binds the current VP set to vp-set. Thus, while a *with-vp-set form is exe¬ 
cuting, the global variables related to VP sets are dynamically bound according to 
the size, shape, and properties of vp-set. 
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The following global variables are affected when the current VP set is changed: 


*current-cm-conf iguration * 
*current-send-address-length* 
*log-number-of-processors-Iimit* 
*number-of-processors-limit* 

* ppp-def ault-start * 


* current-grid-address-lengths* 

*current-vp-set* 

*number-of-dimensions* 

*ppp-default-end* 

t!! nil!! 


Examples- 

Each VP set maintains its own currently selected set of processors. Nested calls to 
*with-vp-set that switch between VP sets also switch between the currently se¬ 
lected sets maintained by the VP sets. This is illustrated by the example shown be¬ 
low. 


(def-vp-set fred '(1024 32)) 

(def-vp-set anne '(512 512) 

:*defvars ((x (!! 1) nil (field-pvar 16)) 

(y (self-address!!)))) 

(*with-vp-set fred ;32,768 VP's 

(♦when (evenp!! self-address!!)) ;16,384 VP's 

(*with-vp-set anne ;262,144 VP's 

(♦set x (-!! y x)) 

(♦with-vp-set fred ;16,384 VP's 

(♦when (not!! (zerop!! (self-address!!))) 

(setq zero-off (*sum (!! 1))) ;16,383 VP's 

(setq zero-on (♦sum (!! 1)))))) ;16,384 VP's 

(♦sum (!! 1))) => 32768 

zero-off => 16383 

zero-on => 16384 

When a VP set is created, it is defined to have all processors selected, so the initial 
call to *with-vp-set fred selects the fred VP set with all virtual processors active. 
The first *when statement reduces the number of active processors in fred by half 
by selecting only even-numbered processors, and the call to *with-vp-$et anne se¬ 
lects the anne VP set, which has 262,144 virtual processors. 
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The second invocation of *with-vp-set f red reselects the f red VP set with the same 
currently selected set as before: only processors of even-numbered addresses are 
active. The second call to *when further restricts the selected set of f red by deacti¬ 
vating processor 0. Inside this 'when statement, a call to (*sum (!! 1)) returns 
16383, the number of active processors in fred. The call to (*sum (!! 1)) immedi¬ 
ately following the ‘when returns 16384, the number of active processors in fred 
with processor 0 included. 

When execution passes back into the *with-vp-set form that originally selected 
the fred VP set, all processors are again active and (*sum (!! 1)) returns 32768, the 
total number of virtual processors in fred. 

If the body of a call to *with-vp-set must be evaluated with all processors selected, 
rather than only those processors currently active in the selected VP set, it should 
be surrounded by a call to *all, as in 

(*with-vp-set fred 
(♦all 

(♦set x (-!! y x)))) 


Notes 


References- 

See also the related operation 

set-vp-set 
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*XOr [Macro] 

Takes the logical XOR of all values in a pvar, returning a scalar value. 


Syntax- 

*xor pvar-expression 


Arguments- 

pvar-expression Pvar expression. Pvar to which global XOR is applied. 


Returned Value- 

xor-scalar Scalar boolean value. The logical XOR of the values of 

pvar-expression in all active processors, i.e., the value t if an odd 
number of the values are non-nil, and the value nil otherwise. 


Side Effects 

None. 


Description- 

The *xor function is a global operator. It takes the logical XOR of all values in a 
pvar, returning a scalar value. Effectively, *xor treats the value of pvar-expression 
in all active processors as a set of boolean values. It returns the value t if an odd 
number of those values are non-nil, and returns the value nil. 

If there are no active processors, this function returns nil. 
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Examples-- 

(*xor t!!) => NIL ;;; t in all processors 

(*xor nil!!) => NIL ;;; t in no processors 

;;; t in every other processor 

(*xor (evenp!! (self-address!!))) => NIL 

(*xor (oddp!! (self-address!!))) => NIL 

;;; t in every third processor (an odd number) 

(*xor (zerop!! (mod!! (self-address!!) (!! 3)))) => T 

;;; an example using non-boolean values 
(*xor (if!! (zerop!! (self-address!!)) 
nil! ! 

(self-address!!))) => T ;;; All but one non-NIL 


Notes 


References- 

See also the related global operators: 

*and * integer-length *logand 

*logior *logxor *max 

*min *or *sum 

See also the related logical operators: 

and!! not!! or!! xor!! 
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XOr!! [Function] 

Performs a parallel logical XOR operation in all active processors. 


Syntax- 

xor!! &rest pvar-exprs 


Arguments- 

pvar-exprs Pvar expressions. Pvars to which parallel XOR is applied. 


Returned Value- 

xor-pvar Temporary boolean pvar. Contains in each active processor the 

logical XOR of the corresponding values of the pvar-exprs. If no 
pvar-exprs are given then nil!! is returned. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description-- 

This performs the XOR function on all the pvar-exprs. If no pvar-exprs are given 
then nil!! is returned. In each processor, xor!! returns t if an odd number of the 
supplied pvar-exprs have the value t in that processor, and otherwise returns nil. 
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Examples- 

(xor!! (evenp!! (self-address!!)) 

(oddp!! (self-address!!))) <=> t!! 

(ppp (xor!! (self-address!!) 

(evenp!! (self-address!!))) 

tend 8) 

NIL T NIL T NIL T NIL T 


Notes 


References- 

See also the related global operators: 


and 

•integer-length 

•logand 

logior 

•logxor 

•max 

min 

*or 

•sum 

xor 




See also the related logical operators: 

and!! not!! or!! 
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zerop!! [Function] 

Performs a parallel test for zero values on the supplied pvar. 

Syntax- 

zerop!! numeric-pvar 

Arguments- 

numeric-pvar Numeric pvar. Tested in parallel for zero values. 

Returned Value- 

zerop-pvar Temporary boolean pvar. Contains the value t in each active 

processor where the corresponding value of numeric-pvar is 
zero. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 

Description- 

This is the parallel equivalent of the Common Lisp function zerop. 
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Examples- 

(zerop!! (mod!! (self-address!!) (!! 2))) 
<=> 

(evenp!! (self-address!!)) 

Notes- 

References- 
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!! [Function] 

Returns a temporary pvar with the same value in each active processor. 


Syntax- 

!! scalar-expression 


Arguments- 

scalar-expression Scalar expression. The value to be stored in each processor of 
the returned pvar. The data type of scalar-expression must be 
either a number, a character, an array, or a structure. 

Returned Value- 

constant-pvar A temporary pvar with the value of scalar-expression in each 
active processor. 


Side Effects- 

Allocates the new temporary pvar on the stack. 


Description- 

The *Lisp function !! creates and returns a temporary pvar containing the value of 
scalar-expression in each active processor. The value of scalar-expression must be 
either a number, a character, an array, or a structure. A temporary pvar is created, 
and a copy of the scalar value is stored in each active processor of the new pvar. 
The temporary pvar is then returned. 

If scalar-expression evaluates to an array, a complete copy of the array is stored in 
each active processor. If the array has a fill pointer, it is ignored; all elements of the 
array are copied into the CM. Adjustable arrays are copied and stored as fixed-size 
arrays. Displaced arrays are copied and stored as non-displaced arrays. The data 
type of the returned pvar depends on the data types of the elements in the array. If 
the array contains elements of various types, the *Lisp rules of type coercion apply. 
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If scalar-expression evaluates to a scalar structure object (of a structure type 
defined by a call to *defstruct) an equaip copy of the object is stored in each active 
processor of the returned pvar. 


Examples-- 

By distributing a single scalar value to all processors, the !! function provides the 
same functionality in *Lisp as scalar values provide in Common Lisp (see 
Figure 6). 

A typical call to !! is very simple. 

(!! 5) ;;; Returns a pvar with 5 in each processor 



(I! ' 

V 


1 1 1 1 1 1 1 1 1 1 

Temporary c c 

Pvar ° ° 

5 5 

5 

5 5 5 • • • 5 5 



Figure 6. The expression (!! 5 ) distributes a scalar value (5) to all processors. 


In *Lisp, !! is most often used to pass a constant value to a function, as in 
(random!! (!! 10)) 

The function random! ! expects a single pvar argument whose value in each proces¬ 
sor is the upper bound of the random number to be calculated in that processor. 
The above example returns a temporary pvar containing a random value between 0 
and 9 in each processor. Note that this differs from 

(random!! (1+!! (self-address!!))) 

which returns a pvar whose value in each processor is a random number between 0 
and the processor’s send address. Here, the pvar argument has a different value in 
every processor. 
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As the following example demonstrates,!! is very useful in comparisons. 

(<!! (self-address!!) (!! 256)) 

This returns a pvar with t in each processor whose send address is less than 256, 
and nil in all other active processors. 

The following is a call to !! with an array argument: 

(*defvar parallel-array (!! #(1 2 3))) 

(ppp parallel-array) 

#(1 2 3) #(1 2 3) #(1 2 3) . . . #<1 2 3) #(1 2 3) 

(setq *print-array* t) 

(pref parallel-array 1) => #(1 2 3) 


This creates a pvar with a copy of the array #(1 2 3) in each processor. Using pref, 
the copy of the array in each processor is accessed. Individual elements of the par¬ 
allel arrays may be accessed using aref. 

Nested arrays of arbitrary depth are legal arguments to !!. For instance, an array of 
arrays is a permissible argument to !!. The expression 

(!! #( #(2 4) #(6 12) #(7 16) #(5 20) #(2 56) )) 

creates a pvar with an array of arrays in each processor. Calling !! with nested ar¬ 
rays can be a very slow operation. 

An example using structures is 
(*defstruct elephant 

(wrinkles 30000 :type (unsigned-byte 16)) 

(tusks t :type boolean)) 

(!! (make-elephant :wrinkles 0 :tusks nil)) 

This creates a pvar with a wrinkle-free, tuskless elephant in each processor. 
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Notes- 

It is an error to call!! with an array containing elements that cannot, according to 
the *Lisp rules of type coercion, be coerced into a single, fixed-size type. 

For example, 

(!! #(1 2 3 #\e #\r #\r #\o #\r #\!)) 
is in error because the array argument contains both integers and characters. 


References- 

See also the pvar allocation and deallocation operations 


allocate!! 

array!! 


’deallocate 

* deallocate-'defvars 

’defvar 

front-end!! 

Met 

Met* 

make-array!! 

typed-vector!! 

vector!! 
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=!! [Function] 

Performs a parallel comparison of the supplied pvars for numerical equality. 


Syntax- 

=!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Compared in parallel for equality. 
numeric-pvars Numeric pvars. Compared in parallel for equality. 

Returned Value- 

equal-pvar Temporary boolean pvar. Contains the value t in each active 

processor where all of the supplied numeric-pvar arguments 
have the same value. Contains nil in all other active processors. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function =!! performs a parallel comparison for numerical equality. It returns 
a temporary pvar that contains t in each active processor where the argument pvars 
contain numerically equal values, and nil in all other active processors. In this way, 
=!! provides the same functionality for numeric pvars as the Common Lisp com¬ 
parison operator = provides for numeric scalars. 

If only one argument pvar is given, the returned pvar is t!!. 
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Examples- 

The function =!! can be used to compare the values of a pvar with some constant 
value. For example, if numeric-pvar contains the values 0,5,1, -4,5, etc., then the 
pvar returned by 


(=!! numeric-pvar (!! 5)) 
contains the values nil, t, nil, nil, t, etc. 

Similarly, one pvar can be compared with another. The expression 

(==! ! numeric-pvar (self-address!!)) 

returns a pvar with the value t in each processor for which numeric-pvar is numeri¬ 
cally equal to that processor’s send address. 

The =!! operator is especially useful in combination with the processor selection 
operators. For example, 

(*when (=!! (mod!! (self-address!!) (!! 4)) 

(!! 3)) 

(*set a (! ! 0))) 

sets the pvar a to zero in every fourth processor. The mod!! function is used to 
divide the send address of each processor, modulo 4, and *when is used to select 
only those processors in which the result is numerically equal to 3. In the selected 
processors, *set sets the pvar a to 0. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 


References 
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/=!! 


/ = !! [Function] 

Performs a parallel comparison of the supplied pvars for numerical inequality. 


Syntax- 

/=!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Compared in parallel for inequality. 
numeric-pvars Numeric pvars. Compared in parallel for inequality. 


Returned Value- 

not-equal-pvar Temporary boolean pvar. Contains the value nil in each active 
processor where any two of the supplied numeric-pvar argu¬ 
ments have the same numeric value. Contains t in all other 
active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The function /=!! performs a parallel comparison for numerical inequality. It re¬ 
turns a temporary pvar that contains nil in each active processor where any two of 
the argument pvars contain numerically equal values, and t in all other active pro¬ 
cessors. In this way, /=!! provides the same functionality for numeric pvars as the 
Common Lisp comparison operator /= provides for numeric scalars. 

If only one argument pvar is given, the returned pvar is tl!: 
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Examples- 

The function /=!! can be used to compare the values of a pvar in with some constant 
value. For example, if numeric-pvar contains the values 0, 5,1, -4, 5, etc., then the 
pvar returned by 


(/=!! numeric-pvar (!! 5)) 
contains the values t, nil, t, t, nil, etc. 

Similarly, one pvar can be compared with another. The expression 

(/=!! numeric-pvar (self-address!!)) 

returns a pvar with the value t in each processor for which numeric-pvar is not 
equal to that processor’s send address. 

The /=!! operator is especially useful in combination with the processor selection 
operators. For example, 

(♦when (/=!! (mod!! (self-address!!) (!! 2)) 

(!! 0 )) 

(♦set a (!! 1))) 

sets the pvar a to one in every odd processor. The mod! ! function is used to divide 
the send address of each processor, modulo 2, and *when is used to select the odd 
processors, i.e., those processors in which the result is not numerically equal to 0. 
In the selected processors, *set sets the pvar a to 1. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 


References 
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<!! [Function] 

Performs a parallel comparison of the supplied pvars for ascending numerical order. 


Syntax- 

<!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Compared in parallel for ascending order. 
numeric-pvars Numeric pvars. Compared in parallel for ascending order. 


Returned Value- 

less-than-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the values of the supplied numeric-pvar argu¬ 
ments are in ascending numerical order. Contains nil in all oth¬ 
er active processors. 

Side Effects-- 

The returned pvar is allocated on the stack. 


Description- 

The <!! function performs a parallel comparison for ascending numerical order. It 
returns a temporary pvar that contains t in each active processor where the values 
of the supplied numeric-pvar arguments are in strictly ascending numerical order, 
and nil in all other active processors. In this way, <!! provides the same functional¬ 
ity for numeric pvars as the Common Lisp comparison operator < provides for 
numeric scalars. 

If there are only two pvar arguments, <!! tests whether each value of the first is less 
than the corresponding value of the second. If only one argument pvar is given, the 
returned pvar is t!!. 
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Examples- 

The function <!! can be used to compare the values of a pvar with some constant 
value. For example, if numeric-pvar contains the values 0,10,1,6,5, etc., then the 
pvar returned by 

(<!! numeric-pvar (!! 5)) 

contains the values t, nil, t, nil, nil, etc. 

Similarly, one pvar can be compared with another. The expression 

(<!! numeric-pvar (self-address!!)) 

returns a pvar with the value t in each processor for which numeric-pvar is less 
than the processor’s send address. 

The <!! operator is especially useful in combination with the processor selection 
operators. For example, 

(*when (<!! data-pvar (!! 10)) 

(♦set data-pvar (*!! data-pvar (!! 2)))) 

multiplies data-pvar by two in processors where data-pvar is less than 10. The mac¬ 
ro *when is used with <!! to select processors where data-pvar is less than 10. The 
value of data-pvar in those processors is multiplied by 2 using *!! and stored back 
into data-pvar by *set. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 


References 
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>!! [Function] 

Performs a parallel comparison of the supplied pvars for descending numerical order. 


Syntax- 

>!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Compared in parallel for descending order. 
numeric-pvars Numeric pvars. Compared in parallel for descending order. 


Returned Value- 

greater-than-pvar Temporary boolean pvar. Contains the value t in each active 
processor where the values of the supplied numeric-pvar argu¬ 
ments are in descending numerical order. Contains nil in all 
other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The >!! function performs a parallel comparison for descending numerical order. 
It returns a temporary pvar that contains t in each active processor where the val¬ 
ues of the supplied numeric-pvar arguments are in strictly descending numerical 
order, and nil in all other active processors. In this way, >!! provides the same func¬ 
tionality for numeric pvars as the Common Lisp comparison operator > provides 
for numeric scalars. 

If there are only two pvar arguments, >!! tests whether each value of the first is 
greater than the corresponding value of the second. If only one argument pvar is 
given, the returned pvar is t!!: 
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Examples-— 

The function >!! can be used to compare the values of a pvar with some constant 
value. For example, if numeric-pvar contains the values 0,10,1,6,5, etc., then the 
pvar returned by 

(>!! numeric-pvar (!! 5)) 

contains the values nil, t, nil, t, nil, etc. 

Similarly, one pvar can be compared with another. The expression 

(>!! numeric-pvar (self-address!!)) 

returns a pvar with the value t in each processor for which numeric-pvar is greater 
than that processor’s send address. 

The >!! operator is especially useful in combination with the processor selection 
operators. For example, 

(*when (>!! data-pvar (!! 10)) 

(*set data-pvar (*!! data-pvar (!! 2)))) 

multiplies data-pvar in processors where data-pvar is greater than 10. The macro 
•when is used with >!! to select processors where data-pvar is greater than 10. The 
value of data-pvar in those processors is multiplied by 2 using *!! and stored back 
into data-pvar by *set. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 


References 
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< = !! [Function] 

Performs a parallel comparison of the supplied pvars for non-descending numerical 
order. 


Syntax 


<=!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Compared in parallel for non-descending or¬ 
der. 

numeric-pvars Numeric pvars. Compared in parallel for non-descending or¬ 
der. 


Returned Value- 

less-than-or-equal-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the values of the supplied numeric-pvar argu¬ 
ments are in non-descending numerical order. Contains nil in 
all other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The <=!! function performs a parallel comparison for non-descending numerical 
order. It returns a temporary pvar that contains t in each active processor where 
the values of the supplied numeric-pvar arguments are in non-descending numeri¬ 
cal order, and nil in all other active processors. In this way, <=!! provides the same 
functionality for numeric pvars as the Common Lisp comparison operator <= pro¬ 
vides for numeric scalars. 
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If there are only two pvar arguments, <=!! tests whether each value of the first is less 
than or equal to the corresponding value of the second. If only one argument pvar is 
given, the returned pvar is t!!: 


Examples- 

The function <=!! can be used to compare the values of a pvar with some constant 
value. For example, if numeric-pvar contains the values 0,10,1,6,5, etc., then the 
pvar returned by 

(<=!! numeric-pvar (!! 5)) 

contains the values t, nil, t, nil, t, etc. 

Similarly, one pvar can be compared with another. The expression 

(<=!! numeric-pvar (self-address!!)) 

returns a pvar with the value t in each processor for which numeric-pvar is less 
than or equal to the processor’s send address. 

The <=!! operator is especially useful in combination with the processor selection 
operators. For example, 

(*when (<=!! data-pvar (!! 10)) 

(*set data-pvar (*!! data-pvar (!! 2)))) 

multiplies data-pvar in processors where data-pvar is less than or equal to 10. The 
macro *when is used with <=!! to select processors where data-pvar is less than to 
equal to 10. The value of data-pvar in those processors is multiplied by 2 using *!! 
and stored back into data-pvar by *set. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 


References 
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> = !! [Function] 

Performs a parallel comparison of the supplied pvars for non-ascending numerical or¬ 
der. 


Syntax- 

>=!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Compared in parallel for non-ascending order. 
numeric-pvars Numeric pvars. Compared in parallel for non-ascending order. 

Returned Value- 

greater-than-or-equal-pvar 

Temporary boolean pvar. Contains the value t in each active 
processor where the values of the supplied numeric-pvar argu¬ 
ments are in non-ascending numerical order. Contains nil in all 
other active processors. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The >=!! function performs a parallel comparison for non-ascending numerical or¬ 
der. It returns a temporary pvar that contains t in each active processor where the 
values of the supplied numeric-pvar arguments are in strictly descending numeri¬ 
cal order, and nil in all other active processors. In this way, >=!! provides the same 
functionality for numeric pvars as the Common Lisp comparison operator >= pro¬ 
vides for numeric scalars. 
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If there are only two pvar arguments, >=!! tests whether each value of the first is 
greater than or equal to the corresponding value of the second. If only one argu¬ 
ment pvar is given, the returned pvar is t!!: 


Examples- 

The function >=!! can be used to compare the values of a pvar with some constant 
value. For example, if numeric-pvar contains the values 0,10,1,6,5, etc., then the 
pvar returned by 

(>=!! numeric-pvar (!! 5)) 

contains the values nil, t, nil, t, t, etc. 

Similarly, one pvar can be compared with another. The expression 

(>=!! numeric-pvar (self-address!!)) 

returns a pvar with the value t in each processor for which numeric-pvar is greater 
than or equal to the processor’s send address. 

The >=!! operator is especially useful in combination with the processor selection 
operators. For example, 

(♦when (>=!! data-pvar (!! 10)) 

(♦set data-pvar (*!! data-pvar (!! 2)))) 

multiplies data-pvar by two in processors where data-pvar is greater than or equal 
to 10. The macro *when is used with >=!! to select processors where data-pvar is 
greater than or equal to 10. The value of data-pvar in those processors is multiplied 
by 2 using *!! and stored back into data-pvar by *set. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 


References 
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+!! [Function] 

Performs a parallel addition of the supplied pvars. 


Syntax- 

+!! &rest numeric-pvars 


Arguments- 

numeric-pvars Numeric pvars. Summed in parallel. 


Returned Value- 

sum-pvar Temporary numeric pvar. In each active processor, contains 

the sum of the corresponding values of the numeric-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The +!! function performs a parallel addition operation. It returns a temporary 
pvar that contains in each active processor the sum of the corresponding values of 
the numeric-pvar arguments. The + !! function provides the same functionality for 
numeric pvars as the Common Lisp addition function + provides for numeric sca¬ 
lars. 

If no arguments are given, (!! 0) is returned. 


Examples- 

The function +!! can be used to increment a pvar by some constant value. For ex¬ 
ample, 
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(+!! numeric-pvar (!! 5)) 

returns a pvar whose value in each processor is the value of numeric-pvar plus 5. 
Similarly, +!! can be used to take the sum of several pvars. The expression 

(+!! position-pvar velocity-pvar (1-!! (random!! (!! 3)))) 

returns a temporary pvar containing in each processor the sum of position-pvar 
and velocity-pvar plus a random number between -1 and 1. 

The +!! operator can be used together with the processor selection operators to 
increment the values of a selected group of processors. For example, 

(*when (<!! plant-height-pvar (!! 12)) 

(*set plant-stand-height-pvar 

(+!! plant-stand-height-pvar (!! 6)))) 

uses +!! to change the height of a set of plant-stands for plants which are below a 
given height in inches. The macro *when is used with <!! to select those processors 
in which plant-height-pvar is less than 12. In these processors, + !! is used with *set 
to add 6 to plant-stand-height-pvar. 


Notes-- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 

If the data types of the argument pvars differ, the *Lisp rules of type coercion ap¬ 
ply. 


References 
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-!! [Function] 

Performs a parallel subtraction or negation of the supplied pvars. 


Syntax- 

-!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Value subtracted from, or negated if no other 
arguments are supplied. 

numeric-pvars Numeric pvars. Values subtracted, in order, from numeric- 
pvar argument. 


Returned Value- 

difference-pvar Temporary numeric pvar. In each active processor, contains 
the result of the subtraction or negation of the corresponding 
values of the pvar arguments. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The -!! function performs a parallel subtraction operation. It returns a temporary 
pvar that contains in each active processor the result of subtracting each of the 
numeric-pvars from numeric-pvar. The - !! function provides the same functional¬ 
ity for numeric pvars as the Common Lisp subtraction function - provides for nu¬ 
meric scalars. 

If only one numeric-pvar argument is given, the value of the returned pvar in each 
active processor is the negation of the corresponding value of numeric-pvar. 

(-!! (!! 9)) <=> (!! (- 9)) 
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Examples- 

The function -!! can be used to decrement a pvar by a constant value. For example, 

(-!! numeric-pvar (!! 5)) 

returns a pvar whose value in each processor is the corresponding value of numer¬ 
ic-pvar minus 5. 

Similarly, -!! can be used to find the difference of several pvars. The expression 

(-!! particles-pvar protons-pvar neutrons-pvar) 

returns a temporary pvar containing in each processor the result of subtracting 
protons-pvar and neutrons-pvar from particles-pvar in that processor. 

The -!! operator can be used together with the processor selection operators to 
decrement the values of a selected group of processors. For example, 

(*when (>=!! plant-height-pvar (!! 72)) 

(*set plant-stand-height-pvar 

(-!! plant-stand-height-pvar (!! 12)))) 

uses -!! to change the height of a set of plant-stands for plants that are above a 
given height in inches. The macro * when is used with >=!! to select those processors 
in which plant-height-pvar is greater than or equal to 72. In these processors, -!! is 
used with *set to subtract 12 from plant-stand-height-pvar. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 

If the data types of the argument pvars differ, the *Lisp rules of type coercion ap¬ 
ply. 


References 
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*!! 

■ ■ 

Performs a parallel multiplication of the supplied pvars. 


[Function] 


Syntax- 

*!! &rest numeric-pvars 


Arguments- 

numeric-pvars Numeric pvars. Multiplied in parallel. 


Returned Value- 

product-pvar Temporary numeric pvar. In each active processor, contains 
the product of the corresponding values of the numeric-pvars. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The *!! function performs a parallel multiplication operation. It returns a tempo¬ 
rary pvar that contains in each active processor the product of the corresponding 
values of the numeric-pvars. The *!! function provides the same functionality for 
numeric pvars as the Common Lisp multiplication function * provides for numeric 
scalars. 

If no arguments are given, then (!! 1) is returned. 


Examples- 

The *!! function can be used to multiply a pvar by some constant value. For exam¬ 
ple, 
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(*!! numeric-pvar (!! 5)) 

returns a pvar whose value in each processor is the corresponding value of numer¬ 
ic-pvar multiplied by 5. 

Similarly, *!! can be used to find the product of several pvars. The expression 

(*!! tower-height-pvar block-mass-pvar gravity-pvar) 

returns a temporary pvar containing in each processor the product of the values of 
tower-height-pvar, block-mass-pvar, and gravity-pvar for that processor. 

The *!! operator can be used together with the processor selection operators to 
modify the values of a selected group of processors. For example, 

(*when (>=!! baggage-weight-pvar (!! 150)) 

(*set passenger-charge-pvar 

(*!! current-rate-pvar (!! 2)))) 

uses *!! to change the fare for passengers with excess baggage. The macro * when is 
used with >=!! to select those processors in which baggage-weight-pvar is greater 
than or equal to 150. In these processors, *!! is used with *set to store twice the 
value of current-rate-pvar in passenger-charge-pvar. 


Notes- 

An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. 

If the data types of the argument pvars differ, the *Lisp rules of type coercion ap¬ 
ply. 


References 
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/!! [Function] 

Performs a parallel division or inversion of the supplied pvars. 


Syntax- 

/!! numeric-pvar &rest numeric-pvars 


Arguments- 

numeric-pvar Numeric pvar. Value to be divided, or inverted if no other argu¬ 

ments are supplied. 

numeric-pvars Numeric pvars. Values by which to divide numeric-pvar argu¬ 
ment. 


Returned Value- 

quotient-pvar Temporary numeric pvar. In each active processor, contains 
the result of the division or inversion of the corresponding val¬ 
ues of the pvar arguments. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The /!! function performs a parallel division operation. It returns a temporary pvar 
that contains in each active processor the result of successively dividing numeric- 
pvar by each of the specified numeric-pvars. The /!! function provides the same 
functionality for numeric pvars as the Common Lisp division function / provides 
for numeric scalars, with the exception that / always returns floating-point or com¬ 
plex valued pvars. 
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If only one numeric-pvar argument is given, the value of the returned pvar in each 
active processor is the inverse of the corresponding value of numeric-pvar. 

(/!! (!! 9)) <=> (!! (/ 9)) 


Examples- 

The function /!! can be used to divide a pvar by a constant value. For example, 

(/!! numeric-pvar (!! 5)) 

returns a pvar whose value in each processor is the corresponding value of numer¬ 
ic-pvar divided by 5. 

Similarly, /!! can be used to find the quotient of several pvars. The expression 

(/!! mass-pvar width-pvar length-pvar) 

returns a temporary pvar containing in each processor the result of dividing mass- 
pvar first by width-pvar and then by length-pvar, in each processor. 

The /!! operator can be used together with the processor selection operators to 
modify the values of a selected group of processors. For example, 

(*when (<!! data-pvar (!! 1)) 

(*set data-pvar (/!! data-pvar))) 

uses /!! to invert all values in data-pvar which are less than 1. The macro *when is 
used with <!! to select those processors in which data-pvar is less than 1. In these 
processors, /!! is used to calculate the reciprocal of data-pvar. The function *set is 
used to store the result back into data-pvar. 


Notes- 

Because there is no parallel analogue of rational numbers in *Lisp, the function / !! 
always returns a pvar containing either floating-point or complex values. 

If there is only one argument, it is an error if numeric-pvar has the value 0 in any 
active processor. If there is more than one argument, it is an error if any of the 
numeric-pvars has the value 0 in any active processor. 
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An error is signalled if any of the numeric-pvar arguments contains a non-numeric 
value in any active processor. If the data types of the argument pvars differ, the 
*Lisp rules of type coercion apply. 


References 
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1 +!! 


1 + !! [Function] 

Performs a parallel addition of 1 to the supplied pvar. 


Syntax- 

1+!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Incremented in parallel by one. 

Returned Value- 

increment-pvar Temporary numeric pvar. In each active processor, contains 
the corresponding value of numeric-pvar incremented by one. 

Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The 1+M function performs a parallel increment operation. It returns a temporary 
pvar that contains in each active processor the result of adding 1 to the correspond¬ 
ing value of numeric-pvar. The 1+!! function provides the same functionality for 
numeric pvars as the Common Lisp incrementing function 1+ provides for numer¬ 
ic scalars. 


Examples- 

The 1+!! function is a contraction of the expression 
(+!! numeric-pvar (!! 1)) 


and performs identically. 
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Notes- 

An error is signalled if the numeric-pvar argument contains a non-numeric value in 
any active processor. 


References- 

The function *incf can be used to destructively increment its argument pvar. See 
the dictionary entry on *incf for more information. 
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1 -!! 


1 -!! [Function] 

Performs a parallel subtraction of 1 from the supplied pvar. 


Syntax- 

1 -!! numeric-pvar 


Arguments- 

numeric-pvar Numeric pvar. Decremented in parallel by one. 

Returned Value- 

decrement-pvar Temporary numeric pvar. In each active processor, contains 
the corresponding value of numeric-pvar decremented by one. 


Side Effects- 

The returned pvar is allocated on the stack. 


Description- 

The 1-!! function performs a parallel decrement operation. It returns a temporary 
pvar that contains in each active processor the result of subtracting 1 from the cor¬ 
responding value of numeric-pvar. The 1 -!! function provides the same functional¬ 
ity for numeric pvars as the Common Lisp decrementing function 1- provides for 
numeric scalars. 


Examples- 

The 1-M function is a contraction of the expression 
(-!! numeric-pvar (!! 1)) 


and performs identically. 
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Notes- 

An error is signalled if the numeric-pvar argument contains a non-numeric value in 
any active processor. 


References- 

The function *decf can be used to destructively decrement its argument pvar. See 
the dictionary entry on *decf for more information. 
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